自动生成注释文档
环境
- Linux系统,python3
- 使用命令安装sphinx:
$ pip install sphinx
- 确保项目能够在该环境中正常编译
流程
- 将项目代码拷贝到linux服务器上。
- cd进入到项目路径中,创建docs文件夹存放sphinx生成的文件:
$ mkdir docs
- 进入docs路径下,初始化sphinx。
$ cd docs/
$ sphinx-quickstart
在初试化配置中,需要表明project name、author name等信息。
- 完成初始化后,需修改和补充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'
- 执行命令:
$ sphinx-apidoc -o source/ ../
$ make html
如果生成过程出现错误,则在更正后再次执行 make html 命令,直到成功为止。
- 最终生成的html文件在 docs/build 目录下。