安裝
直接使用 pip3 install sphinx 即可
開始
建一個存放文檔的 docs 目錄,進入 docs 目錄執行: sphinx-quickstart
填寫信息的按自己的清空填寫即可,有兩個插件在安裝過程中需要啓用:
-
autodoc: automatically insert docstrings from modules (y/n) [n]: y 很重要,輸入y
-
viewcode: include links to the source code of documented Python objects (y/n) [n]: y 很重要,輸入y,表示將源碼也放到文檔中,你看很多python的模塊的文檔,其實都是包含代碼的。
修改配置文件 conf.py
- 設置要處理的路徑(注1): sys.path.insert(0, os.path.abspath('..'))
- 如果前面的該啓用的插件沒用啓用,可以在這裏手動啓用一下
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.coverage",
"sphinx.ext.doctest",
"sphinx.ext.intersphinx",
"sphinx.ext.viewcode",
]
生成所需的 rst 文檔
返回 docs 目錄的上一級,對當前目錄的每一個文件夾及子文件夾生成一個rst文件,對應python的包,存放在./docs目錄下:
sphinx-apidoc -o ./docs/ .
注意:
- 這裏第一個路徑要和注1一致
- 如果之前生成過,添加 -f 參數即可覆蓋
生成 HTML
進入 docs 目錄,執行命令:make html
注意
- 代碼中的執行要用下面的判斷包裝一下,否則可能導致 sphinx 等待代碼執行,或者直接不動
if __name__ == '__main__':
pass
- 如果代碼中有自定義的包的路徑,也要在配置文件中添加, sys.path.append("path") 即可
- 如果路徑中包含 modules 字樣的可能有問題
參考了: https://blog.csdn.net/suzyu12345/article/details/52923464