用python寫了一個螢幕自動控制的開源小專案
，需要編寫文件，這可能是程式設計師最痛苦的工作了，哈哈。
為了儘量減少工作量，API呼叫部分最好能直接用原始碼註釋生成——這樣至少不用寫兩遍了，而且註釋離原始碼最近，相互對照寫起來方便。
摸索了一下生成工具，發現還不是那麼簡單。目前成熟可用的有三個：
- Pydocs：python環境自帶，但是有點過於簡單，只能一個個指定檔案/類/模組來生成文件，生成的內容預設輸出到控制檯，還得重定向到檔案，優勢是原生支援Markdown。當然另外兩個工具又過於複雜了點，沒有找到類似JavaDoc那樣平衡的工具
- Sphinx：老牌文件生成工具，和下面的MkDocs一樣，都是完整的文件組織管理工具，可以生成Html文件，全套文件要當做一個專案來管理。如果要從原始碼註釋生成文件，需要安裝autodoc等擴充套件。Sphinx最大的缺點在於要使用一種叫做reStructuredText（.rst檔案）的文件格式，很是彆扭。詳見使用 Sphinx 為專案自動生成 API 文件
- MkDocs：相對新的文件管理工具，通過Markdown格式來組織文件，安裝外掛Mkdocstrings以後，也支援從原始碼註釋生成md檔案。網上也有比較詳細的教程，本文主要補充一點踩過的坑。
首先呢，MkDocs是把文件當成專案來管理的，我們編寫的markdown檔案，相當於“文件原始碼”，會被它“編譯”成Html（支援多種風格），而Mkdocstrings這個外掛，是從python原始碼中提取註釋，生成mk格式的“文件原始碼”。
剛接觸的時候，我們可能會猶豫：這個專案和原本的python專案是什麼關係呢？其實除了要提取註釋，兩個專案沒關係。大可以放心地在原python專案裡建一個目錄，用 mkdocs new 指令新建一個文件專案。
新建專案以後，mkdocs會在指定目錄下，生成一個yaml格式的配置檔案，再新建一個docs目錄，作為“文件原始碼”所在位置，並且生成一個名為index.md的預設文件。
為了支援註釋生成文件，需要pip安裝mkdocstrings，然修改mkdocs.yml配置檔案，啟用這個外掛
plugins:
- mkdocstrings然後在自己的md檔案裡（或者生成的index.md，取決於想在哪裡生成）用特殊格式引入python原始碼的模組名，例如：
## generated
::: autopy # autopy是模組名，可以寫多級，比如autopy.core.data這樣，前面的三個冒號，表示這裡需要呼叫mkdocstrings來生成之後命令列呼叫 mkdocs build，會生成相應的html檔案，或者呼叫 mkdocs serve 啟動一個本地http伺服器，通過瀏覽器來預覽。此時可能會報錯：提示找不到指定的模組，這很可能是python原始碼沒有加入系統路徑造成的。
我們當然可以把原始碼路徑直接加到PATHONPATH環境變數中，但這樣會有影響其他程式的副作用，而且還得按絕對路徑加，不夠靈活。好在mkdocstrings配置夠強大，支援動態程式碼，此時可以補充mkdocs.yml檔案裡補充handlers：
plugins:
- mkdocstrings
handlers:
python:
setup_commands:
- import sys
- sys.path.insert(0, "..")這裡等於告訴mkdocstring，提取註釋前，先執行setup_commands中的語句，通過sys.path.insert，把父目錄新增進來（我們前面是在python原始碼目錄下，新建了文件專案，所以對文件專案來說，原始碼就是父目錄）。
再次執行mkdocs serve ，就會發現生成的html文件中，::: autopy 這部分，已經被程式碼中的註釋替換掉了。
注意：Mkdocs要求程式碼註釋符合谷歌規範。