搜尋 Sphinx 時很容易撞到另一個同名老牌全文檢索引擎,但這裡要談的是文件工具:由 Georg Brandl 在 BSD 授權下開發,用 reStructuredText 寫作、輸出成網站或 PDF 的那一套。
它最早是為了改寫 Python 官方文件而生,如今已是 Python 專案的標準文件方案,對 C/C++ 專案也有良好支援。Python 官方文件本身就是它最有說服力的樣品。主要特色包括:
以下以 Debian 5 為示範環境,其他發行版概念相同。
下載與安裝:https://www.python.org/download/
多數 Linux 發行版已預裝 Python,可用 python --version 確認版本。
它是安裝 easy_install 的前提,而 easy_install 是我們下一步要用的套件管理器。
Windows:直接下載對應 Python 版本的 exe 安裝檔,執行即可。例如 Python 2.7 對應:
https://pypi.python.org/packages/2.7/s/setuptools/setuptools-0.6c11.win32-py2.7.exe
Mac OS X / Linux:先下載對應版本的 egg 檔(我的環境是 Python 2.6.6):
wget https://pypi.python.org/packages/2.6/s/setuptools/setuptools-0.6c11-py2.6.egg
然後執行安裝:
sh setuptools-0.6c11-py2.6.egg
完成後 easy_install 指令就可以用了。
補充一點:在較新的系統上,setuptools 已逐步被 pip 取代,多數發行版可以直接用套件管理器安裝(Debian/Ubuntu 為 apt-get install python-pip),會省下不少功夫。
easy_install -U Sphinx
若使用 pip,則為:
pip install -U Sphinx
安裝完成後,執行 sphinx-quickstart 就能開始建立第一份文件專案了。