Sphinx生成python文檔示例圖文解析
前言
Sphinx是一款支持多種編程語言的文檔生成工具，在python項目開發(fā)過程中，可以幫助開發(fā)者根據需求生成相應的說明文檔，拿今天我們就基于該開源工具進行一個入門的實踐。
安裝
pip3 install sphinx
環(huán)境準備
1. 安裝python，pycharm編輯器的電腦
2. 創(chuàng)建相關的項目目錄，如下圖所示，我們可以創(chuàng)建document_generate_sphinx的項目文件夾，在下面分別創(chuàng)建doc和src文件夾，前者用來存放sphinx工具生成的相關文檔和配置文件，后者用來存放自己的項目源碼文件。
3. 在src文件夾下創(chuàng)建demo_one.py和demo_two.py文件，并寫上簡單的幾個類和測試代碼，在doc目錄下運行sphinx-quickstart，一路默認配置下來會生成如下圖所示存在于doc文件夾中的文件（這其中除了要配置自己的項目名稱，版本號等內容外，其他均默認或者yes即可）
3. 接下來，我們可以運行sphinx-apidoc -o ../doc ../src/ 命令將源碼生成rst文件到doc的文件夾下，如下圖
4. 到此，我們就可以嘗試 在doc目錄下 運行make html指令來生sphinx說明文檔了，但是在這里發(fā)生了報錯如下
從報錯的內容來看分為兩類，第一個是在提示我們沒有發(fā)現automodule，第二個是發(fā)現modules.rst文件中沒有toctree。
經過實踐我們得到解決第一個問題需要在conf.py文件中添加上extensions = ["sphinx.ext.autodoc"]插件即可，解決第二個問題，需要在index.rst文件中添加上modules的文件路徑，如下所示
5. 此時，我們再去運行make clean&make html指令，可以清除之前生成的文檔，生成新的文檔在build或者_build文件夾中，打開_build文件夾html文件夾中的index.html文件可以發(fā)現生成的文檔如下圖
6. 在實際閱讀開源庫的說明文檔過程中會發(fā)現，目前python的很多開源文檔都是統(tǒng)一的藍白交替的主題，為了讓自己顯得更專業(yè)，可以為其替換一下目前流行的主題，在替換主題前，需要安裝一下主題庫，并在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目錄下直接人為創(chuàng)建一個非py代碼的說明文件，命名為changelog.rst，然后直接運行make clean&make html指令，得到了如下報錯
從報錯內容的提示來看，是因為changelog文件沒有被放到toctree中，所以需要在index.rst文件中添加上changelog的目錄，如下圖所示
9. 再次運行make clean&make html指令，編譯順利成功，但是發(fā)現打開文檔目錄中index后，顯示特別丑，個人建議可以將其刪掉，原圖如下
10. 刪除掉index.rst文件中紅色部分，如下左圖，然后再次編譯生成新的文檔，可以發(fā)現沒有了索引模塊，顯得簡單干凈，如下右圖所示。
11. 如果在開發(fā)過程中更改了源代碼需要展示的文件，需要重新運行生成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指令，發(fā)現編譯成功，文檔也更新了相關模塊和內容，另外會有人說，如果需要在文檔中展示的函數能夠鏈接到源碼，需要怎么做，這里很簡單。
12. 文檔展示函數鏈接源碼，在conf.py文件中extensions中添加"sphinx.ext.viewcode"模塊 重新生成文檔如下
結語
至此，Sphinx文檔生成的簡單入門示例就完成啦，如果需要更深入的研究和探討，大家可以參考sphinx的官方文檔。
以上就是Sphinx生成python文檔示例圖文解析的詳細內容，更多關于Sphinx生成python文檔的資料請關注腳本之家其它相關文章！
相關文章
這篇文章主要介紹了爬蟲被封的問題，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-04-04
這篇文章主要介紹了Python基于回溯法子集樹模板解決馬踏棋盤問題,簡單描述了國際象棋馬踏棋盤問題,并結合實例形式分析了Python使用回溯法子集樹模板解決馬踏棋盤問題的具體步驟與相關操作注意事項,需要的朋友可以參考下2017-09-09
在本篇文章里我們給大家分享的是關于Python使用Shelve保存對象的知識點總結，有興趣的朋友們學習下。2019-01-01
今天小編就為大家分享一篇python3 打開外部程序及關閉的示例，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2018-11-11
這篇文章主要給大家介紹了關于python中numpy包的使用教程，包含數組和相關操作等內容，文中通過示例代碼介紹的非常詳細，對大家具有一定的參考學習價值，需要的朋友們下面來跟著小編一起學習學習吧。2017-07-07
這篇文章主要介紹了python?數據挖掘算法,首先給大家介紹了數據挖掘的過程，基于sklearn主要的算法模型講解，給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下2022-02-02
使用Python向DataFrame中指定位置添加一列或多列的方法
今天小編就為大家分享一篇使用Python向DataFrame中指定位置添加一列或多列的方法，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2019-01-01
今天小編就為大家分享一篇使用Python畫出小人發(fā)射愛心的代碼，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2021-09-09
這篇文章主要為大家詳細介紹了python實現聊天小程序，具有一定的參考價值，感興趣的小伙伴們可以參考一下2018-03-03
這篇文章主要介紹了python操作gmail的方法,實例分析了python針對gmail操作的技巧,具有一定參考借鑒價值,需要的朋友可以參考下2015-01-01