Sphinx生成python檔案範例圖文解析

2022-04-05 16:01:44

前言

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名稱，如下圖