Sphinx是一個可以用於Python的自動文檔生成工具，可以自動的把docstring轉換為文檔，並支持多種輸出格式包括html，latex，pdf等。
安裝
創建一個sphinx項目
下面的命令會自動生成一個默認的Sphinx模板
執行期間，它會一步步的詢問對模板的設置，除了一些必須填寫的選項，大部分填寫默認值就行了，你會遇到這樣一條叫autodoc的，需要選擇yes
然后默認的目錄就生成了，大概是這個樣子
現在執行如下指令，就會生成一份空文檔，存放在/build/html里，點擊index.html就可以打開一個空的網頁，雖然沒有內容，但是整體的結構還是在的
source/ 目錄
source/目錄里有兩個文件，分別是conf.py和index.rst，下面對它們進行進一步的介紹
index.rst
.rst是reStructuredText，和Markdown一樣是一種標記語言，具體的語法可以看這里 reStructuredText Primer。
實際上，我們在使用Sphinx的過程中最主要就是對這些rst文件進行修改，而Sphinx所做的事情就是讀取這些rst文件，並轉換為特定格式的文檔，在前面的步驟中，index.rst實際上被轉換為build/html/index.html，而實際上在rst文檔內你可以寫任何東西，最后這些都會被轉換到輸出文檔中。
打開index.rst,可以看到這樣的內容，這是rst的一個語法，它使用了一個toctree節點，並設置了一些參數，而這個toctree節點是必須的。
conf.py
這是運行sphinx生成文檔時會加載的配置，你可以通過對它進行修改來改變生成文檔的行為。
一個具體的例子
假設現在我們有一個叫run.py的文件，如下
那么需要如何生成文檔呢？下面一步步帶你完成
- 創建一個文件夾demo/，並將run.py放到里面
- 在demo里創建一個docs目錄，進入docs/目錄，當然這里你可以隨意選定文件夾，只是這樣更規范一些
- 生成Sphinx默認模板，設置項目名為demo，並開啟autodoc
運行sphinx-quickstart
- 進入source目錄，打開index.rst
- 將index.rst 修改為如下，實際上這里面可以寫任何滿足rst規范的內容
這個是用於自動從模塊讀取docstring的語句，可以自動從run模塊讀取文檔
- 但是現在還差一步，如果你現在直接生成文檔，會告訴你找不到run模塊，因為Sphinx默認只會從sys.path里加載模塊，所以需要將demo目錄加入sys.path，所以現在打開conf.py，添加如下內容
- 運行Sphinx生成html文檔
-
現在，打開build/html/index.html就可以看到如下界面了
-
、 -
格式進一步優化
上面的例子涵蓋了大多數常用操作，但是通常文檔都不是扁平的，而是層次化的，那么要如何將文檔層次化的分門別類。
實際上在rst文檔中是可以以鏈接的形式引用其他rst文檔的，也就是說我們可以自由的對文檔結構進行組織使其更易讀下面我們把run的文檔移動到一個單獨的頁面，只在index.rst里保留跳轉鏈接。在source目錄下創建run.rst
-
然后將index.rst對應位置的內容刪掉，並進行修改
-
:doc:'Run API</run>'表示對一個文檔的引用，這里引用了當前目錄的run.rst，現在重新生成html，就會看到頁面顯示上的變化了。