摘要：
Sphinx可以根据python注释自动生成接口文档，这有利于确保文档和代码函数的同步。˃自动文档：automaticallyinsertdocstringsfrommodules（y/n）[n]：默认情况下选择其他项后，将在当前目录中创建文档目录，所有与斯芬克斯相关的文件将位于文档目录$lsdoc/__buildconf.pyindex.rstMakefile _static_Templates$vidoc/conf中。py#修改文件内容sys。路径插入系统。路径insert#缺少此行将导致在执行html__import__错误时出现提示，模块未找到。因此，必须将上层目录包含在$sphinxapidocodoc/中。创建文件文件/a。第一。创建文件文档/模块。rst#添加生成的文档/模块。第一个索引。rst$vidoc/指数。rst内容：。。扭矩：：最大深度：2个模块。rst在doc/_Build/html中生成html页面$cddoc$makehtml生成的html文档。狮身人面像对只适用于蟒蛇2.7或蟒蛇3。
写好了代码，交付给他人使用的时候，查看代码固然可以了解各类和函数的功能细节，但接口文档能更方便的查找和说明功能。所以，一价与代码同步的接口文档是很有必要的。sphinx可以根据python中的注释，自动的生成接口文档，这样有利于保证文档和代码功能的同步。让我们来了解如何自动生成文档。
1. python代码格式。
class A: ''' 你好！ ''' @staticmethod def Aa(): ''' 你也好！ ''' fun1()
看到类和函数中，都加入了注释。
2. 安装shpinx
pip install sphinx -i https://pypi.doubanio.com/simple --trusted-host pypi.doubanio.com
使用国内的镜像安装比较快。
3. 配置shpinx
$ cd myproject $ sphinx-quickstart Enter the root path for documentation. > Root path for the documentation [.]: doc
> Project name: XXX
> Author name(s): XXX
> Project version []: 1.0
> Project release [1.0]:
> Project language [en]: zh_CN #如果注释中有中文，这里必须设置。否则生成接口文档出错。
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
其它项都选择默认
完成之后，会在当前目录创建 doc 目录，所有sphinx相关的文件都在 doc目录下。
$ ls doc/ _build conf.py index.rst Makefile _static _templates $ vi doc/conf.py #修改文件内容 sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('..')) # 缺少此行会导致在make html时提示 __import__出错，找不到module。 所以必须把上一级目录(即代码所在目录)include进来 $ sphinx-apidoc -o doc/ . Creating file doc/a.rst. Creating file doc/modules.rst # 把生成的 doc/modules.rst添加到index.rst $ vi doc/index.rst Contents: .. toctree:: :maxdepth: 2 modules.rst 生成html页面 $ cd doc $ make html
生成的html文档，在doc/_build/html里。
sphinx对仅工作在python2.7 或python3上。当文件中有中文时，可能会报错：'ascii' codec can't decode byte 0xe2 in position xxx。可以在报错的地方加入：
import sys reload(sys) sys.setdefaultencoding('utf-8')