使用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的扩展，可能能简化以上的过程，等我试一试在更新结果。