為自己Coding
為自己Coding

YO~~ 剛跨入AI人工智慧領域的小小工程師, 熱愛自學, 熱愛分享, 下班後的我想為自己Coding, 積極撰寫教學文, 想將自學的程式知識分享給大家, 不斷追求進步的自己, 希望有一天能回饋社會,幫助需要幫助的人, 如果您有什麼很酷的想法,也覺得我還行,歡迎您找我合作~~ IG: https://www.instagram.com/coding_4_me/

Coding起來- Python工具-Sphinx 操作教學


嗨,先來簡單談談為什麼要用Sphinx,相信大家在撰寫程式時,為了讓之後的自己或他人能看得懂,所以非常勤勞在寫註解,而我們的程式專案的產出,文件(doc)是非常重要的,它讓使用者了解我們的專案code在幹麻,Sphinx就是一個非常好的工具,幫我們自動萃取註解成一個可讀檔(html形式),這樣我們就不用上傳完專案,還要重新寫一份文檔來解釋,可以使用Sphinx的方法來修改即可。

Github連結


Step1: 先建立一個資料夾結構

像是建立python_project(folder)裡面有doc 與 src 兩個資料夾

Step2: 將 你的python檔放在src資料夾底下(src 用來存放python code)

建立一個python文件(ex. Example.py),其實就是撰寫python,並保存在src裡面,下面有個範例:

Step3: 在doc(folder) 建立 Sphinx 文件

a.先cd到專案目錄(python-project)底下

(我是用Anaconda Prompt開啟)

b.安裝 sphinx

pip install –U sphinx

c.建立sphinx專案

sphinx-quickstart doc

執行後,它會詢問一些資訊:(你可以自由開心填)

i. Separate source and build directories(y/n): 看你要不要把source 跟 build 資料夾分開,這邊選的是yes

ii. Project name: (專案名稱)

Author name(s): (作者)

Project release []: (版本)

iii. Project language [en] : (語言) 我選的是英文 en,也可以填zh-TW等

接下來就會產生許多我們需要的folder

Step4: 更改doc/source/conf.py檔案

要確保有圖片裡的兩個圈

a. Sys.path… : 設定路徑(設定到src,因為我們的python 在那裡)

b. Sphinx.ext.autodoc: 自動抓取路徑檔案的插件

c. html_theme:更換html主題,讓你的介面不一樣

i. 來點特別的,所以我選擇scrolls來用用看,你可以選擇下面各種選項,我記得我一開它預設是alabaster

官網預設的主題: alabaster、classic、sphinxdoc、scrolls, agogo, traditional, nature , haiku,pyramid, bizstyle、default

參考官網: https://www.sphinx-doc.org/en/master/usage/theming.html

ii. 如果你選擇的是default 或classic,可以加入html_theme_options ={} 來更改裡面的樣式,像是如圖,當然也有很多參數可以自行做調整

我覺得可以參考這篇,寫得非常詳細分常厲害!!

參考這篇: http://kevinchen.synology.me/TechnicalDocuments/Sphinx/Sphinx_module.html

Step5: 再來編輯另一個 doc/source/index.rst rst檔案

a. Index.rst是最後形成html的預設首頁, 加入我們的索引名稱 Example (需要與..toctree:: : 區塊隔一行)

b.(p.s ..toctree:: 是rst檔用來連接外部檔案的)

Step6: 在doc/source/目錄底下建立一個 Example.rst文件 並 撰寫內容,它會是呈現我們程式檔案,並說明的頁面,感覺很抽象,沒關係看下去你就知道了

a. ===========的上面: 是標題的名稱,它會出現在最後html裡面的content標題

b. .. auotmodule:: Example : 它會去自動抓取(之前設定的插件)我們在src底下的檔名(Example)(我們之前設定的路徑)

c. :members: House: 這個程式檔裡面有個House的class (成員) 一定要抓class的名稱 或 function的名稱,不能自己亂抓,但可以選擇不填,讓它自己抓(建議)

Warning: 如果只填一個function或class 的名稱,只會抓到該function或class 的裡面的資料, 但選擇不填 就可以都抓到

Step7: 最後cd 到doc目錄底下

a. 打上 make html,就可以到 doc/build/html/ 看到html檔

b. 預設首頁是index.tml,點開來play

Contents: 裡面有我們預設的主題名稱,點進去看看

Amzaing!! 完成了

希望這次對您也有很大的幫助!!


Reference:

https://www.sphinx-doc.org/en/master/usage/theming.html

http://kevinchen.synology.me/TechnicalDocuments/Sphinx/sphinx_detailed_teach.html

https://myapollo.com.tw/zh-tw/python-autodoc/

http://kevinchen.synology.me/TechnicalDocuments/Sphinx/Sphinx_module.html

CC BY-NC-ND 2.0 版权声明

喜欢我的文章吗?
别忘了给点支持与赞赏,让我知道创作的路上有你陪伴。

加载中…

发布评论