Python Table Manners - 文件


Apr 15, 2020

這裡已經不再維護了,可以到我的個人部落格 看更新的文章

Python 開源專案中,Sphinx 是很常見的文件產生工具
它能將 reStructuredText 寫成的文件轉成網頁
Read the Docs 也直接支援 Sphinx 產生的網頁

但我今天要介紹的工具是 mkdocs
最簡單的原因就是,我只會寫 Markdown 不會寫 reStructuredText XD
Guido 也說簡單一點的文件可以使用 Markdown 而不需使用 Shpinx
(我又要搬同一張截圖出來救援了 XD)

because-guido-say-so

安裝

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/ 就能看到最初始的頁面

initial document

修改網站名稱

初始的 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

separate page

內部連結

撰寫文件時,為了讓使用者更容易找到其他頁面,會使用到內部連結
這時只要在文件中使用跟 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'

material theme

輸出靜態網頁

為了要能部署到其他服務 (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
  • plugins

Bonus: 徽章

在開源專案中,常常可以見到一些有趣的徽章
它們很可能就是用 shields.io 產生的
除了常見的徽章外,也可以透過修改 url 製作客製化的徽章

像是在 markdown 文件加入

![shields badge](https://img.shields.io/badge/<LABEL>-<MESSAGE>-<COLOR>)

就會出現

shields badge

自製測試覆蓋率徽章

最近發現另一個有趣的小工具 - coverage-badge
它可以不透過 codecov 直接去讀 pytest-cov 產生的 .coverage 產生測試覆蓋率徽章

pipenv install coverage-badge --dev
pipenv run coverage-badge -o docs/coverage.svg

Reference

#Python #Documentation







你可能感興趣的文章

React-[路由篇]-SPAs與React Router (上)

React-[路由篇]-SPAs與React Router (上)

Longformer - The Long-Document Transformer

Longformer - The Long-Document Transformer

【JS 專案 - 01】 今晚來點 TodoList...

【JS 專案 - 01】 今晚來點 TodoList...






留言討論