Sphinx 這名字有點容易誤會——本文談的不是那個全文搜尋引擎,而是 Python 社群用來把 reStructuredText 原始檔轉成網站或 PDF 的「文件生成工具」。寫過 Python 官方文件的人應該都看過它的成品樣子。
先切換到你想放文件的位置,例如 /home/wwwroot/doc:
cd /home/wwwroot/doc
接著啟動精靈:
sphinx-quickstart
程式會逐步詢問一些選項,絕大部分直接按 Enter 使用預設值即可。幾個值得留意的問題:
Enter the root path for documentation.
> Root path for the documentation [.]:
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: F2E Cookbook
> Author name(s): imbingdian
> Source file suffix [.rst]: .txt
三個建議:選擇分離 source 與 build 目錄(輸入 y),後續管理清楚得多;專案名稱與作者會出現在產出文件的各處,認真填;文件副檔名預設是 .rst,若團隊習慣用 .txt 就在這裡改。
之後的問題一路 Enter 就好。
完成後,doc 目錄下會多出這些內容:
build/ # 產出的文件放這裡
source/ # 原始檔與 conf.py 設定檔
make.bat
Makefile
試著產生 HTML:
make html
到 build 目錄底下看看,HTML 已經生成好了。
所有設定都集中在 source/conf.py。
找到這行並取消註解:
#language = None
language = 'zh_CN'
其他常見語言代碼:
bn – Bengali ca – Catalan cs – Czech da – Danish
de – German en – English es – Spanish fi – Finnish
fr – French hr – Croatian it – Italian ja – Japanese
lt – Lithuanian nl – Dutch pl – Polish pt_BR – Brazilian Portuguese
ru – Russian sl – Slovenian tr – Turkish uk_UA – Ukrainian
zh_CN – Simplified Chinese zh_TW – Traditional Chinese
找到 html_theme = 'default',把 default 換成想要的名稱即可。官方內建主題清單見:
sphinx.pocoo.org/theming.html
html_title # 瀏覽器分頁與頁首顯示的標題
html_static_path # 放自訂 CSS、圖片的目錄
extensions # 需要啟用的擴充,例如 autodoc、todo、graphviz
latex_documents # 輸出 PDF 時的版型設定
改完設定後,重新執行一次 make html 就會生效。若還需要 PDF,加上 make latexpdf(需先安裝 LaTeX 環境)即可。更細節的設定項目建議直接查閱官方文件,那裡的說明最完整也最新。