写好了代码,交付给他人使用的时候,查看代码固然可以了解各类和函数的功能细节,但接口文档能更方便的查找和说明功能。所以,一价与代码同步的接口文档是很有必要的。sphinx可以根据python中的注释,自动的生成接口文档,这样有利于保证文档和代码功能的同步。让我们来了解如何自动生成文档。
class A:
'''
你好!
'''
@staticmethod
def Aa():
'''
你也好!
'''
fun1()
看到类和函数中,都加入了注释。
- 安装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')