嗨，先來簡單談談為什麼要用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