一  簡單介紹

不管是開源還是閉源，文件都是很重要的。當然理論上說，最好的文件就是程式碼本身，但是要讓所有人都能讀懂你的程式碼這太難了。所以我們要寫文件。大部分情況，我們不希望維護一份程式碼再加上一份文件，這樣做很容易造成文件和程式碼的不一致，程式設計師最討厭更新文件了。所以最佳實踐就是在程式設計師程式碼中加註釋，然後通過構建指令碼自通生成文件，包括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'）

那麼需要如何生成文件呢？下面一步步帶你完成

1. 建立一個資料夾demo/，並將run.py放到裡面
2. 在demo裡建立一個docs目錄，進入docs/目錄，當然這裡你可以隨意選定資料夾，只是這樣更規範一些
3. 生成Sphinx預設模板，設定專案名為demo，並開啟autodoc（執行sphinx-quickstart）
4. 進入source目錄，開啟index.rst
5. 將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，就會看到頁面顯示上的變化了。

參考：使用Sphinx為你的python模組自動生成文件