程序员-工程师-软件开发者

不管是开源还是闭源，文档都是很重要的。当然理论上说，最好的文档就是代码本身，但是要让所有人都能读懂你的代码这太难了。所以我们要写文档。大部分情况，我们不希望维护一份代码再加上一份文档，这样做很容易造成文档和代码的不一致，程序员最讨厌更新文档了。所以最佳实践就是在程序员代码中加注释，然后通过构建脚本自通生成文档。

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