前言

Sphinx是一款支持多種編程語(yǔ)言的文檔生成工具，在python項(xiàng)目開(kāi)發(fā)過(guò)程中，可以幫助開(kāi)發(fā)者根據(jù)需求生成相應(yīng)的說(shuō)明文檔，拿今天我們就基于該開(kāi)源工具進(jìn)行一個(gè)入門的實(shí)踐。

安裝

pip3 install sphinx

環(huán)境準(zhǔn)備

1. 安裝python，pycharm編輯器的電腦

2. 創(chuàng)建相關(guān)的項(xiàng)目目錄，如下圖所示，我們可以創(chuàng)建document_generate_sphinx的項(xiàng)目文件夾，在下面分別創(chuàng)建doc和src文件夾，前者用來(lái)存放sphinx工具生成的相關(guān)文檔和配置文件，后者用來(lái)存放自己的項(xiàng)目源碼文件。

3. 在src文件夾下創(chuàng)建demo_one.py和demo_two.py文件，并寫上簡(jiǎn)單的幾個(gè)類和測(cè)試代碼，在doc目錄下運(yùn)行sphinx-quickstart，一路默認(rèn)配置下來(lái)會(huì)生成如下圖所示存在于doc文件夾中的文件（這其中除了要配置自己的項(xiàng)目名稱，版本號(hào)等內(nèi)容外，其他均默認(rèn)或者yes即可）

3. 接下來(lái)，我們可以運(yùn)行sphinx-apidoc -o ../doc ../src/ 命令將源碼生成rst文件到doc的文件夾下，如下圖

4. 到此，我們就可以嘗試 在doc目錄下 運(yùn)行make html指令來(lái)生sphinx說(shuō)明文檔了，但是在這里發(fā)生了報(bào)錯(cuò)如下

從報(bào)錯(cuò)的內(nèi)容來(lái)看分為兩類，第一個(gè)是在提示我們沒(méi)有發(fā)現(xiàn)automodule，第二個(gè)是發(fā)現(xiàn)modules.rst文件中沒(méi)有toctree。

經(jīng)過(guò)實(shí)踐我們得到解決第一個(gè)問(wèn)題需要在conf.py文件中添加上extensions = ["sphinx.ext.autodoc"]插件即可，解決第二個(gè)問(wèn)題，需要在index.rst文件中添加上modules的文件路徑，如下所示

?5. 此時(shí)，我們?cè)偃ミ\(yùn)行make clean&make html指令，可以清除之前生成的文檔，生成新的文檔在build或者_(dá)build文件夾中，打開(kāi)_build文件夾html文件夾中的index.html文件可以發(fā)現(xiàn)生成的文檔如下圖

?6. 在實(shí)際閱讀開(kāi)源庫(kù)的說(shuō)明文檔過(guò)程中會(huì)發(fā)現(xiàn)，目前python的很多開(kāi)源文檔都是統(tǒng)一的藍(lán)白交替的主題，為了讓自己顯得更專業(yè)，可以為其替換一下目前流行的主題，在替換主題前，需要安裝一下主題庫(kù)，并在conf.py文件中做一個(gè)主題配置。如下

　　6.1 pip3 install sphinx_rtd_theme

　　6.2 在conf.py文件中將 html_theme = "alabaster"更換如下圖，再添加上html_theme_path

?7. 重新運(yùn)行make clean&make html命令，生成的新文檔說(shuō)明如下

?8. 至此，完成了一個(gè)簡(jiǎn)單的兩個(gè)程序代碼的文檔生成示例，但是在實(shí)際項(xiàng)目中，可能還設(shè)計(jì)到其他目錄下文件的添加和變更，怎樣把需要展示的文件展示到文檔中？類如changelog的添加，其他文件的添加。

　　比如，這里在doc目錄下直接人為創(chuàng)建一個(gè)非py代碼的說(shuō)明文件，命名為changelog.rst，然后直接運(yùn)行make clean&make html指令，得到了如下報(bào)錯(cuò)

從報(bào)錯(cuò)內(nèi)容的提示來(lái)看，是因?yàn)閏hangelog文件沒(méi)有被放到toctree中，所以需要在index.rst文件中添加上changelog的目錄，如下圖所示

?9. 再次運(yùn)行make clean&make html指令，編譯順利成功，但是發(fā)現(xiàn)打開(kāi)文檔目錄中index后，顯示特別丑，個(gè)人建議可以將其刪掉，原圖如下

?10. 刪除掉index.rst文件中紅色部分，如下左圖，然后再次編譯生成新的文檔，可以發(fā)現(xiàn)沒(méi)有了索引模塊，顯得簡(jiǎn)單干凈，如下右圖所示。

?11. 如果在開(kāi)發(fā)過(guò)程中更改了源代碼需要展示的文件，需要重新運(yùn)行生成rst文件的指令 sphinx-apidoc -o ../doc ../src/

比如，為了示范，我們將原來(lái)src文件中的demo_one.py 和 demo_two.py分別更名成 animal_attack.py和dog_aonstan.py文件，并重新寫了一些代碼，那么就需要重新運(yùn)行上述指令并刪除原來(lái)的rst文件并更改modules.rst文件中的module名稱，如下圖

再次運(yùn)行make clean&make html指令，發(fā)現(xiàn)編譯成功，文檔也更新了相關(guān)模塊和內(nèi)容，另外會(huì)有人說(shuō)，如果需要在文檔中展示的函數(shù)能夠鏈接到源碼，需要怎么做，這里很簡(jiǎn)單。

12. 文檔展示函數(shù)鏈接源碼，在conf.py文件中extensions中添加"sphinx.ext.viewcode"模塊 重新生成文檔如下

結(jié)語(yǔ)

至此，Sphinx文檔生成的簡(jiǎn)單入門示例就完成啦，如果需要更深入的研究和探討，大家可以參考sphinx的官方文檔。