使用sphinx快速生成Python API 文檔

一  簡單介紹

不論是開源仍是閉源，文檔都是很重要的。固然理論上說，最好的文檔就是代碼自己，可是要讓全部人都能讀懂你的代碼這太難了。因此咱們要寫文檔。大部分狀況，咱們不但願維護一份代碼再加上一份文檔，這樣作很容易形成文檔和代碼的不一致，程序員最討厭更新文檔了。因此最佳實踐就是在程序員代碼中加註釋，而後經過構建腳本自通生成文檔，包括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模塊自動生成文檔