Sphinx 是個用來幫忙在 python 程式中所寫的說明中，自動生成文件的工具。

初始設定

安裝 Sphinx

1	pip install sphinx

可以另外安裝 theme

1	pip install sphinx-rtd-theme

設定資料夾結構
其實也可以不設定，這邊是要分離文件跟原始碼所做的處理

1
2
3

projectRoot
├---src
└---docs

筆者將原始碼統一放在 src/ 資料夾下

在 doc/ 資料夾下執行

1	sphinx-quickstart

然後會有一連串的設定選項要選，但筆者也還沒很了解這些設定，以後有機會再補充。
就會產生所需檔案與 conf.py ，將該檔案內的

1
2
3

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

取消註解，並修改為

1
2
3

import os
import sys
sys.path.insert(0, os.path.abspath('../src/'))

然後在

1 2	extensions = [ ]

加入 'sphinx.ext.autodoc' ，如下所示

1	extensions = ['sphinx.ext.autodoc']

autodoc

這個功能可以引用程式內的註解說明(docstring)，但 Sphinx 有指定的格式^[1]。
若是像筆者習慣使用 vscode ，可以使用 autoDocstring 這個擴充功能，並設定為 Sphinx 的格式。就可以快速插入 docstring 了。

以 src/subFunc/main.py 為例，在 docs/ 的任一 .rst 檔加入以下語法，就會引用該程式碼裡所寫的說明

1 2	.. automodule:: subFunc.main :members:

可以使用 SimpleHTTPServer 建立簡易的網頁伺服器^[2]
在網站的根目錄執行以下指令

1	python -m SimpleHTTPServer

成功的話，會顯示以下訊息

1	Serving HTTP on 0.0.0.0 port 8000 ...

接下來就可以到 http://localhost:8000 查看網頁。