一 簡單介紹
不管是開源還是閉源，文檔都是很重要的。當然理論上說，最好的文檔就是代碼本身，但是要讓所有人都能讀懂你的代碼這太難了。所以我們要寫文檔。大部分情況，我們不希望維護一份代碼再加上一份文檔，這樣做很容易造成文檔和代碼的不一致，程序員最討厭更新文檔了。所以最佳實踐就是在程序員代碼中加注釋，然后通過構建腳本自通生成文檔，包括html，latex，pdf等。
對應於Pyhon，有很多可供選擇的工具：
- sphinx 中文版介紹 Sphinx使用 reStructuredText作為標記語言（類似Markdown），可擴展，功能強大。要注意的是何有一個開源的搜索也叫Sphinx，斯芬克斯果然太受歡迎，開源的世界起個名字不容易呀。
- pdoc 是一個簡單易用的命令行工具，可以生成Python的API文檔
- Doxygen 是老牌的文檔生成工具，可以針對各種語言生成文檔，我們以前在C++的項目中曾經使用過
- 其他還有諸如 pydoc ， pydoctor 等等
二 安裝
- 要安裝Sphinx，不同的操作系統有不同的安裝方式，Sphinx的源代碼在這里 ！
- 你也可以自己構建。我推薦使用pip install sphinx !
- 如果你安裝了Anaconda，Sphinx已經包含在內了!
三 創建一個sphinx項目
下面的命令會自動生成一個默認的Sphinx模板：
mkdir yourdir cd yourdir sphinx-quickstart
執行期間，它會一步步的詢問對模板的設置，除了一些必須填寫的選項，大部分填寫默認值就行了，你會遇到這樣一條叫autodoc的，需要選擇yes！
autodoc: automatically insert docstrings from modules (y/n) [n]
然后默認的目錄就生成了，大概是這個樣子
- yourdir/ # 剛才新建的目錄
- source/ # 存放Sphinx工程源碼
- build/ # 存放生成的文檔
Makefile
現在執行如下指令，就會生成一份空文檔，存放在/build/html里，點擊index.html就可以打開一個空的網頁，雖然沒有內容，但是整體的結構還是在的!
sphinx-build -b html source build make html
source/目錄里有兩個文件，分別是conf.py和index.rst，下面對它們進行進一步的介紹
(1) index.rst
.rst是reStructuredText，和Markdown一樣是一種標記語言，具體的語法可以看這里 reStructuredText Primer。實際上，我們在使用Sphinx的過程中最主要就是對這些rst文件進行修改，而Sphinx所做的事情就是讀取這些rst文件，並轉換為特定格式的文檔，在前面的步驟中，index.rst實際上被轉換為build/html/index.html，而實際上在rst文檔內你可以寫任何東西，最后這些都會被轉換到輸出文檔中。
打開index.rst,可以看到這樣的內容，這是rst的一個語法，它使用了一個toctree節點，並設置了一些參數，而這個toctree節點是必須的。
.. toctree:: :maxdepth: 2 :caption: Contents:
(2) conf.py
這是運行sphinx生成文檔時會加載的配置，你可以通過對它進行修改來改變生成文檔的行為。
四 一個具體的例子
假設現在我們有一個叫run.py的文件，如下
# run.py
def run(name): """ this is how we run :param name name of people who runs """
print （name, 'is running'）
那么需要如何生成文檔呢？下面一步步帶你完成
- 創建一個文件夾demo/，並將run.py放到里面
- 在demo里創建一個docs目錄，進入docs/目錄，當然這里你可以隨意選定文件夾，只是這樣更規范一些
- 生成Sphinx默認模板，設置項目名為demo，並開啟autodoc（運行sphinx-quickstart）
- 進入source目錄，打開index.rst
- 將index.rst 修改為如下，實際上這里面可以寫任何滿足rst規范的內容
Welcome to demo's API Documentation ======================================
.. toctree::
:maxdepth:2
:caption: Contents:
Introduction ============
This is the introduction of demo。
API ===
.. automodule:: run
:members:
Indices and tables ==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
這個是用於自動從模塊讀取docstring的語句，可以自動從run模塊讀取文檔
.. automodule:: run
:members:
但是現在還差一步，如果你現在直接生成文檔，會告訴你找不到run模塊，因為Sphinx默認只會從sys.path里加載模塊，所以需要將demo目錄加入sys.path，所以現在打開conf.py，添加如下內容
import os import sys sys.path.insert(0, os.path.abspath('../..'))
運行Sphinx生成html文檔
cd .. sphinx-build -b html source build make html
現在，打開build/html/index.html就可以看到如下界面了
注：格式進一步優化
上面的例子涵蓋了大多數常用操作，但是通常文檔都不是扁平的，而是層次化的，那么要如何將文檔層次化的分門別類。實際上在rst文檔中是可以以鏈接的形式引用其他rst文檔的，也就是說我們可以自由的對文檔結構進行組織使其更易讀。下面我們把run的文檔移動到一個單獨的頁面，只在index.rst里保留跳轉鏈接。在source目錄下創建run.rst
API === .. automodule:: run :members: Indices and tables ==================
* :ref:`genindex` * :ref:`modindex` * :ref:`search`
然后將index.rst對應位置的內容刪掉，並進行修改
Welcome to demo's API Documentation ===================================
.. toctree::
:maxdepth: 2
:caption: Contents:
Introduction ============
This is the introduction of demo。
API ===
:doc:'Run API</run>'
Indices and tables ==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
:doc:'Run API</run>'表示對一個文檔的引用，這里引用了當前目錄的run.rst，現在重新生成html，就會看到頁面顯示上的變化了。