python利用sphinx自动生成项目的注释文档的方法

自动生成注释文档

环境

• Linux系统，python3
• 使用命令安装sphinx：

$ pip install sphinx

• 确保项目能够在该环境中正常编译

流程

1. 将项目代码拷贝到linux服务器上。
2. cd进入到项目路径中,创建docs文件夹存放sphinx生成的文件：

$ mkdir docs 

3. 进入docs路径下，初始化sphinx。

   $ cd docs/  
   $ sphinx-quickstart  

在初试化配置中，需要表明project name、author name等信息。

4. 完成初始化后，需修改和补充docs/source/conf.py文件中的配置信息。

• 添加拓展信息

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax'
    'sphinx.ext.viewcode'
    ]

• 取消注释，添加路径信息

import os
import sys
sys.path.insert(0, os.path.abspath('../../')) #指向src目录

• 更改主题风格

html_theme = 'sphinx_rtd_theme'

5. 执行命令：

$ sphinx-apidoc -o source/ ../
$ make html

如果生成过程出现错误，则在更正后再次执行 make html 命令，直到成功为止。

6. 最终生成的html文件在 docs/build 目录下。