前言

Sphinx是一款支持多種編程語言的文檔生成工具，在python項目開發過程中，可以幫助開發者根據需求生成相應的說明文檔，拿今天我們就基于該開源工具進行一個入門的實踐。

安裝

pip3 install sphinx

環境準備

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

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

3. 在src文件夾下創建demo_one.py和demo_two.py文件，并寫上簡單的幾個類和測試代碼，在doc目錄下運行sphinx-quickstart，一路默認配置下來會生成如下圖所示存在于doc文件夾中的文件（這其中除了要配置自己的項目名稱，版本號等內容外，其他均默認或者yes即可）

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

4. 到此，我們就可以嘗試 在doc目錄下 運行make html指令來生sphinx說明文檔了，但是在這里發生了報錯如下

從報錯的內容來看分為兩類，第一個是在提示我們沒有發現automodule，第二個是發現modules.rst文件中沒有toctree。

經過實踐我們得到解決第一個問題需要在conf.py文件中添加上extensions = ["sphinx.ext.autodoc"]插件即可，解決第二個問題，需要在index.rst文件中添加上modules的文件路徑，如下所示

?5. 此時，我們再去運行make clean&make html指令，可以清除之前生成的文檔，生成新的文檔在build或者_build文件夾中，打開_build文件夾html文件夾中的index.html文件可以發現生成的文檔如下圖

?6. 在實際閱讀開源庫的說明文檔過程中會發現，目前python的很多開源文檔都是統一的藍白交替的主題，為了讓自己顯得更專業，可以為其替換一下目前流行的主題，在替換主題前，需要安裝一下主題庫，并在conf.py文件中做一個主題配置。如下

　　6.1 pip3 install sphinx_rtd_theme

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

?7. 重新運行make clean&make html命令，生成的新文檔說明如下

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

　　比如，這里在doc目錄下直接人為創建一個非py代碼的說明文件，命名為changelog.rst，然后直接運行make clean&make html指令，得到了如下報錯

從報錯內容的提示來看，是因為changelog文件沒有被放到toctree中，所以需要在index.rst文件中添加上changelog的目錄，如下圖所示

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

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

?11. 如果在開發過程中更改了源代碼需要展示的文件，需要重新運行生成rst文件的指令 sphinx-apidoc -o ../doc ../src/

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

再次運行make clean&make html指令，發現編譯成功，文檔也更新了相關模塊和內容，另外會有人說，如果需要在文檔中展示的函數能夠鏈接到源碼，需要怎么做，這里很簡單。

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

結語

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