python sphinx 自動化文檔的用法

安裝

直接使用 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