這裡已經不再維護了，可以到我的個人部落格 看更新的文章
Python 開源專案中，Sphinx 是很常見的文件產生工具
它能將 reStructuredText 寫成的文件轉成網頁
Read the Docs 也直接支援 Sphinx 產生的網頁
但我今天要介紹的工具是 mkdocs
最簡單的原因就是，我只會寫 Markdown 不會寫 reStructuredText XD
Guido 也說簡單一點的文件可以使用 Markdown 而不需使用 Shpinx
（我又要搬同一張截圖出來救援了 XD）
安裝
pipenv install mkdocs --dev
使用
這次依然是將 mkdocs 運用到 pycontw-postevent-report-generator 為例子
在 commit 3fab5b 版之後產生將文件從 README.md 移動到 docs 並產生 GitHub Page
初始化
首先進到專案資料夾中，初始化 mkdocs 需要的檔案
pipenv run mkdir new .
執行後，資料夾會多出以下兩個檔案
mkdocs.yml: mkdocs 的設定檔doc/index.md: 空白的範例文件
透過這個指令在本機將伺服器跑起來
pipenv run mkdocs serve
打開瀏覽器，進入 http://127.0.0.1:8000/ 就能看到最初始的頁面
修改網站名稱
初始的 mkdocs.yml 預設只會有這一行
site_name: My Docs
指的是文件的頁面名稱，先把它改成專案的名稱
site_name: PyCon TW post-event report generator (rg-cli)
增加頁面
因為 GitHub 也會讀 docs/READMD.md 作為進入專案時看到的文件
為了減少維護文件的時間，可以將 README.md 移動到 docs ，並取代掉 index.md 做為首頁
因為原先在 pycontw-postevent-report-generator 中的 README.md 有點長
我將 How to contribute 的內容拆出來放到 contributing.md
將檔案命名成 contributing.md 在 GitHub 開 issue 時自動出現這個頁面的連結（See more 👉 Setting guidelines for repository contributors）
至於要怎麼寫好 contributing.md 則可以參考 Wrangling Web Contributions: How to Build a CONTRIBUTING.md
├── docs
│ ├── README.md
│ └── contributing.md
接著在 mkdocs.yml 加入 nav 參數，指定不同頁面對應的檔案
site_name: PyCon TW post-event report generator (rg-cli)
nav:
- Home: index.md
- Contributing: contributing.md
位置是透過參數 docs_dir 來決定相對路徑
如果沒有設定，預設是相對於 docs
內部連結
撰寫文件時，為了讓使用者更容易找到其他頁面，會使用到內部連結
這時只要在文件中使用跟 mkdocs.yml 一樣的相對路徑即可
e.g., 在 README.md 連結到 contributing.md
Please see the [Contributing](contributing.md) for further details.
更改主題
mkdocs 預設有 mkdocs, readthedocs 兩種主題
如果想嘗試其他主題則可以在 MkDocs Themes 找到
以主題 mkdocs-material 為例
首先先將主題安裝到開發環境內
pipenv install mkdocs-material --dev
在 mkdocs.yml 加上 theme 參數
需要注意的是這裡的 name 不需要加上前綴的 mkdocs-
site_name: rg-cli
nav:
- Home: index.md
- Contributing: contributing.md
theme:
name: 'material'
輸出靜態網頁
為了要能部署到其他服務 (e.g., GitHub Page）上，要先在本地將 Markdown 寫成的文件輸出成網頁
pipenv run mkdocs build
接著就可以在資料夾 site 找到輸出的網頁
因為 site 的內容都會跟著 docs 改變，專案中只需要留有原始的 Markdown 文件就好
可以在 .gitignore 加入 site/
echo "site/" >> .gitignore
下次輸出時，在指令後面加上 --clean 就可以清空上次的內容，重新輸出
pipenv run mkdocs build --clean
部署至 GitHub Page
在開源專案中，將文件部署到 GitHub Page 上是相當常見的
mkdocs 也為我們考慮到這點
只要在 mkdocs.yml 加入專案的 remote 相關設定
repo_url: https://github.com/pycontw/pycontw-postevent-report-generator
remote_branch: gh-pages
remote_name: origin
並執行 pipenv run mkdocs gh-deploy 就會自動將文件部署到 GitHub Page 上
如果想更近一步透過 GitHub Action 來達到 push 原始碼，就自動產生 GitHub Page
可以參考我之前寫的 透過 GitHub Action 自動發佈 Pelican 部落格文章
雖然裡面使用的例子是 Pelican ，但只要把建置頁面的指令換掉就可以了
其他 mkdocs.yml 常用設定
- site_description, site_author, copyright
- google_analytics
- markdown_extensions
- mkdocs 解析 Markdown 文件時要使用 Python Markdown 的 extension 和其設定
- plugins
- 預設會使用 search 套件，如果想使用其它套件可以在 MkDocs-Plugins 找到
Bonus: 徽章
在開源專案中，常常可以見到一些有趣的徽章
它們很可能就是用 shields.io 產生的
除了常見的徽章外，也可以透過修改 url 製作客製化的徽章
像是在 markdown 文件加入
就會出現
自製測試覆蓋率徽章
最近發現另一個有趣的小工具 - coverage-badge
它可以不透過 codecov 直接去讀 pytest-cov 產生的 .coverage 產生測試覆蓋率徽章
pipenv install coverage-badge --dev
pipenv run coverage-badge -o docs/coverage.svg
