使用sphinx快速生成Python API 文檔

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

對應於Pyhon，有不少可供選擇的工具：

• sphinx 中文版介紹 Sphinx使用 reStructuredText做爲標記語言（相似Markdown），可擴展，功能強大。要注意的是何有一個開源的搜索也叫Sphinx，斯芬克斯果真太受歡迎，開源的世界起個名字不容易呀。

• pdoc 是一個簡單易用的命令行工具，能夠生成Python的API文檔

• Doxygen 是老牌的文檔生成工具，能夠針對各類語言生成文檔，咱們之前在C++的項目中曾經使用過

• 其餘還有諸如 pydoc ， pydoctor 等等

下面我就介紹一下若是使用Sphinx爲你的python項目快速的構建API 文檔。

首先要安裝Sphinx，不一樣的操做系統有不一樣的安裝方式，Sphinx的源代碼在這裏 ， 你也能夠本身構建。我推薦使用pip install。（注，若是你安裝了Anaconda，Sphinx已經包含在內了）

而後，假定你的python的源代碼是在 src 目錄下，咱們在同一級並行創建一個文檔目錄 doc （你固然能夠根據本身的項目須要，肯定目錄命名和結構）。

在doc目錄下運行 

sphinx-quickstart

sphinx會提示你的項目的一些設置，生成項目的配置文件，這裏給出一些推薦的配置：

> Root path for the documentation [.]:
<ENTER>
> Separate source and build directories (y/N) [n]:
y
> Name prefix for templates and static dir [_]:
<ENTER>
> Project name:
an_example_pypi_project
> Author name(s):
Andrew Carter
> Project version:
0.0.1
> Project release [0.0.1]:
<ENTER>
> Source file suffix [.rst]:
<ENTER>
> Name of your master document (without suffix) [index]:
<ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]:
y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
y
> todo: write 「todo」 entries that can be shown or hidden on build (y/N) [n]:
n
> coverage: checks for documentation coverage (y/N) [n]:
n
> pngmath: include math, rendered as PNG images (y/N) [n]:
n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
y
> Create Makefile? (Y/n) [y]:
n
> Create Windows command file? (Y/n) [y]:
n

運行完畢，sphinx會生成項目的配置文檔conf.py還有源文件（後綴爲rst）

下一步要爲捏python源文件生成sphinx的源文件，用來生成API文檔，須要運行

sphinx-apidoc [options] -o outputdir packagedir [pathnames]

其中outputdir是doc目錄，packagedir是src目錄，也就是你的python代碼包所在的目錄

運行好後，會對每個Python包生成一個rst文件，你能夠編輯該文件來修改生成文檔的細節，通常狀況下不用改。

好了，準備工做作好了之後，就能夠生成API文檔了。在運行文檔生成腳本以前，要確保你的Python源代碼所在的包在系統路徑中是能夠找到的，須要修改conf.py。由於在生成文檔是須要運行你的python代碼，要保證code運行不出錯。

sys.path.insert(0, os.path.abspath('../src'))

在doc目錄下運行腳本

sphinx-build -b html . ./ouput

在output目錄會生成HTML格式的API文檔。（也能夠選其餘文檔格式）

Sphinx還有一個automsummay的擴展，可能能簡化以上的過程，等我試一試在更新結果。