自动生成API文档

我们需要使用sphinx-apidoc来代码文件生成对应rst文件，使用方法如下：

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

比如我们把源代码放在source文件夹的getYiyi文件夹里，要在source文件夹下生成rst文件，则需要运行如下命令：

$ sphinx-apidoc -o ./ getYiyi

运行后会生成modules.rst和对应每个代码文件名rst文件。我们在index.rst里引用生成的modules文件即可以将生成的文档集成进来。

除此以外，我们还需要进行一些设置。

  • 修改conf.py文件，将以下内容：
#import os
#import sys
#sys.path.insert(0, os.path.abspath(''))

修改为：:

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

这是为sphinx指定了保存Python代码的路径。

警告

Sphinx需要导入python模块来提取docstring，所以一定要记着加上 if __name__ == ‘__main__’ 这一条件。

如果你还想添加查看源代码的功能，需要在extension里加入 'sphinx.ext.viewcode',。

最后生成的结果如下：

../_images/source.JPG

文档内容可以在Indices and tables中进行检索。

../_images/index.JPG