學(xué)習(xí)sphinx制作文檔
摘要
本篇中的sphinx不是開發(fā)搜索功能的軟件鸯匹，而是生成文檔的工具。它使用reStructuredText編寫文檔灾搏，這是一種類似Markdown的簡單標記語言挫望。
比Markdown強大之處在于，它支持使用代碼編寫數(shù)學(xué)公式狂窑，使用代碼制作流程圖等圖片媳板，最后由sphinx解析成各種文件，比如HTML泉哈、PDF等蛉幸。
所以，Markdown適合于單篇無體系的文章丛晦，而Sphinx更適合用于寫作具有緊密聯(lián)系的一些列文章奕纫，比如讀書筆記、書稿等烫沙。
windows下使用sphinx
安裝
安裝 python
下載 python匹层，下載地址：Windows x86-64 web-based installer
各版本解釋
x86 適合 32 位操作系統(tǒng)，x86-64適合64位操作系統(tǒng)锌蓄。
web-based installer 是需要通過聯(lián)網(wǎng)完成安裝的又固。我的理解是仲器，下載的是一部分，全部安裝包是
在啟動此 installer 后仰冠，通過網(wǎng)絡(luò)獲取的乏冀。
executable installer 是可執(zhí)行文件(*.exe)方式安裝。下載下來的就是全部安裝包洋只。
embeddable zip file 嵌入式版本辆沦，可以集成到其它應(yīng)用中。不理解识虚。
下載安裝包之后肢扯，直接雙擊安裝。
安裝 sphinx
打開CMD担锤，執(zhí)行命令
pip install Sphinx
CMD 窗口出現(xiàn)錯誤信息：
PermissionError: [WinError 5] 拒絕訪問蔚晨。: 'c:\\program files\\python35\\Lib\\site-packages\\pytz'
You are using pip version 8.1.1, however version 8.1.2 is available.
You should consider upgrading via the 'python -m pip install --upgrade pip' command.
執(zhí)行命令
python -m pip install --upgrade pip
仍然出現(xiàn)同樣的錯誤。難道是用戶權(quán)限問題肛循。切換到管理員用戶執(zhí)行命令
python -m pip install --upgrade pip
屏幕打印信息
C:\WINDOWS\system32>python -m pip install --upgrade pip
Collecting pip
Using cached pip-8.1.2-py2.py3-none-any.whl
Installing collected packages: pip
Found existing installation: pip 8.1.1
Uninstalling pip-8.1.1:
Successfully uninstalled pip-8.1.1
Successfully installed pip-8.1.2
成功更新了pip铭腕。再回到普通用戶執(zhí)行安裝 Sphinx 的命令
pip install Sphinx
屏幕打印信息的最后一部分
File "c:\program files\python35\lib\site-packages\pip\utils\__init__.py", line 83, in ensure_dir
os.makedirs(path)
File "c:\program files\python35\lib\os.py", line 241, in makedirs
mkdir(name, mode)
PermissionError: [WinError 5] 拒絕訪問。: 'c:\\program files\\python35\\Lib\\site-packages\\colorama'
仍然是權(quán)限問題多糠。在管理員CMD下再執(zhí)行安裝Sphinx命令
pip install Sphinx
屏幕打印信息最后一部分
Running setup.py install for MarkupSafe ... done
Successfully installed Jinja2-2.8 MarkupSafe-0.23 Pygments-2.1.3 Sphinx-1.4.6
alabaster-0.7.9 babel-2.3.4 colorama-0.3.7 docutils-0.12 imagesize-0.7.1 pytz-2016.6.1
six-1.10.0 snowballstemmer-1.2.1
安裝sphinx成功了累舷。
設(shè)置 the documentation sources
執(zhí)行命令
sphinx-quickstart
運行結(jié)果如下圖
根據(jù)需要回答它的一系列問題，對于 “autodoc” extension夹孔，一定要回答 y被盈。
關(guān)于語言的回答，英文選擇 en搭伤，簡體中文選擇 zh_CN只怎， 繁體中文選擇 zh_TW。
最后的運行結(jié)果是這樣的
Creating file H:/sphinx\source\conf.py.
Creating file H:/sphinx\source\index.rst.
Creating file H:/sphinx\Makefile.
Creating file H:/sphinx\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file H:/sphinx\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
定義文檔結(jié)構(gòu)--Defining document structure
編譯文檔 - Running the build
執(zhí)行命令
sphinx-build -b html sourcedir builddir
這條命令不能直接執(zhí)行怜俐，需根據(jù)自己的需要修改身堡。
-b，選擇需要的編譯器佑菩，即要編譯成什么格式的文件。
sourcedir裁赠，要編譯的源文件路徑殿漠。必須設(shè)置。
builddir佩捞，編譯后的文件輸出的路徑绞幌。必須設(shè)置。
執(zhí)行命令
sphinx-build -b html H:/sphinx/source H:/sphinx/build
執(zhí)行成功后一忱，以前為空的 H:/sphinx/build 目錄下面出現(xiàn)了很多文件莲蜘。
.
├── Makefile
├── build
├── source
└── make.bat
- Makefile：它是一個包含指令的文件谭确，在使用 make 命令時，可以使用這些指令來構(gòu)建文檔輸出票渠。
- build：這是觸發(fā)特定輸出后用來存放所生成的文件的目錄逐哈。
- source：源代碼目錄。
- make.bat：使用
make html可以取代sphinx-build -b html问顷。
