Sphinx生成python文檔示例圖文解析
前言
Sphinx是一款支持多種編程語言的文檔生成工具，在python項(xiàng)目開發(fā)過程中，可以幫助開發(fā)者根據(jù)需求生成相應(yīng)的說明文檔，拿今天我們就基于該開源工具進(jìn)行一個入門的實(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文件夾，前者用來存放sphinx工具生成的相關(guān)文檔和配置文件，后者用來存放自己的項(xiàng)目源碼文件。
3. 在src文件夾下創(chuàng)建demo_one.py和demo_two.py文件，并寫上簡單的幾個類和測試代碼，在doc目錄下運(yùn)行sphinx-quickstart，一路默認(rèn)配置下來會生成如下圖所示存在于doc文件夾中的文件（這其中除了要配置自己的項(xiàng)目名稱，版本號等內(nèi)容外，其他均默認(rèn)或者yes即可）
3. 接下來，我們可以運(yùn)行sphinx-apidoc -o ../doc ../src/ 命令將源碼生成rst文件到doc的文件夾下，如下圖
4. 到此，我們就可以嘗試 在doc目錄下 運(yùn)行make html指令來生sphinx說明文檔了，但是在這里發(fā)生了報錯如下
從報錯的內(nèi)容來看分為兩類，第一個是在提示我們沒有發(fā)現(xiàn)automodule，第二個是發(fā)現(xiàn)modules.rst文件中沒有toctree。
經(jīng)過實(shí)踐我們得到解決第一個問題需要在conf.py文件中添加上extensions = ["sphinx.ext.autodoc"]插件即可，解決第二個問題，需要在index.rst文件中添加上modules的文件路徑，如下所示
5. 此時，我們再去運(yùn)行make clean&make html指令，可以清除之前生成的文檔，生成新的文檔在build或者_(dá)build文件夾中，打開_build文件夾html文件夾中的index.html文件可以發(fā)現(xiàn)生成的文檔如下圖
6. 在實(shí)際閱讀開源庫的說明文檔過程中會發(fā)現(xiàn)，目前python的很多開源文檔都是統(tǒng)一的藍(lán)白交替的主題，為了讓自己顯得更專業(yè)，可以為其替換一下目前流行的主題，在替換主題前，需要安裝一下主題庫，并在conf.py文件中做一個主題配置。如下
6.1 pip3 install sphinx_rtd_theme
6.2 在conf.py文件中將 html_theme = "alabaster"更換如下圖，再添加上html_theme_path
7. 重新運(yùn)行make clean&make html命令，生成的新文檔說明如下
8. 至此，完成了一個簡單的兩個程序代碼的文檔生成示例，但是在實(shí)際項(xiàng)目中，可能還設(shè)計到其他目錄下文件的添加和變更，怎樣把需要展示的文件展示到文檔中？類如changelog的添加，其他文件的添加。
比如，這里在doc目錄下直接人為創(chuàng)建一個非py代碼的說明文件，命名為changelog.rst，然后直接運(yùn)行make clean&make html指令，得到了如下報錯
從報錯內(nèi)容的提示來看，是因?yàn)閏hangelog文件沒有被放到toctree中，所以需要在index.rst文件中添加上changelog的目錄，如下圖所示
9. 再次運(yùn)行make clean&make html指令，編譯順利成功，但是發(fā)現(xiàn)打開文檔目錄中index后，顯示特別丑，個人建議可以將其刪掉，原圖如下
10. 刪除掉index.rst文件中紅色部分，如下左圖，然后再次編譯生成新的文檔，可以發(fā)現(xiàn)沒有了索引模塊，顯得簡單干凈，如下右圖所示。
11. 如果在開發(fā)過程中更改了源代碼需要展示的文件，需要重新運(yùn)行生成rst文件的指令 sphinx-apidoc -o ../doc ../src/
比如，為了示范，我們將原來src文件中的demo_one.py 和 demo_two.py分別更名成 animal_attack.py和dog_aonstan.py文件，并重新寫了一些代碼，那么就需要重新運(yùn)行上述指令并刪除原來的rst文件并更改modules.rst文件中的module名稱，如下圖
再次運(yùn)行make clean&make html指令，發(fā)現(xiàn)編譯成功，文檔也更新了相關(guān)模塊和內(nèi)容，另外會有人說，如果需要在文檔中展示的函數(shù)能夠鏈接到源碼，需要怎么做，這里很簡單。
12. 文檔展示函數(shù)鏈接源碼，在conf.py文件中extensions中添加"sphinx.ext.viewcode"模塊 重新生成文檔如下
結(jié)語
至此，Sphinx文檔生成的簡單入門示例就完成啦，如果需要更深入的研究和探討，大家可以參考sphinx的官方文檔。
以上就是Sphinx生成python文檔示例圖文解析的詳細(xì)內(nèi)容，更多關(guān)于Sphinx生成python文檔的資料請關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
pytest進(jìn)階教程之fixture函數(shù)詳解
這篇文章主要給大家介紹了關(guān)于pytest進(jìn)階教程之fixture函數(shù)的相關(guān)資料，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2021-03-03
python深度學(xué)習(xí)TensorFlow神經(jīng)網(wǎng)絡(luò)模型的保存和讀取
這篇文章主要為大家介紹了python深度學(xué)習(xí)TensorFlow神經(jīng)網(wǎng)絡(luò)如何將訓(xùn)練得到的模型保存下來方便下次直接使用。為了讓訓(xùn)練結(jié)果可以復(fù)用，需要將訓(xùn)練好的神經(jīng)網(wǎng)絡(luò)模型持久化2021-11-11
13行python代碼實(shí)現(xiàn)對微信進(jìn)行推送消息的示例代碼
本文主要介紹了13行python代碼實(shí)現(xiàn)對微信進(jìn)行推送消息的示例代碼，文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2022-08-08
這篇文章主要介紹了Python可變對象和不可變對象的相關(guān)資料,文中講解非常細(xì)致，代碼幫助大家更好的理解和學(xué)習(xí)，感興趣的朋友可以了解下2021-09-09
pytest自定義命令行參數(shù)的實(shí)現(xiàn)
本文主要介紹了在使用pytest運(yùn)行測試用例時,通過傳遞自定義命令行參數(shù)來啟動mitmdump進(jìn)程進(jìn)行抓包,具有一定的參考價值,感興趣的可以了解一下2024-12-12
這篇文章主要介紹了如何通過Python制作一個簡易的音樂播放器，文中的示例代碼講解詳細(xì)，對我們學(xué)習(xí)或工作有一定價值，需要的可以參考一下2022-02-02
在本篇文章里小編給大家整理了關(guān)于python全棧的知識點(diǎn)以及學(xué)習(xí)路線的總結(jié)，需要的朋友們參考下。2019-07-07
這篇文章主要介紹了django中資源文件夾的引入,主要包括靜態(tài)資源文件夾的引入及媒體資源文件夾的引入，本文給大家介紹的非常詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2022-08-08
這篇文章主要介紹了Pandas-DataFrame知識點(diǎn)匯總，DataFrame是一種表格型數(shù)據(jù)結(jié)構(gòu)，它含有一組有序的列，每列可以是不同的值，下面我們一起進(jìn)入文章了解更多詳細(xì)內(nèi)容吧，需要的小伙伴也可以參考一下2022-03-03
這篇文章主要介紹了用matplotlib畫等高線圖詳解，具有一定借鑒價值，需要的朋友可以參考下。2017-12-12