python sphinx 自动化文档的用法

安装

直接使用 pip3 install sphinx 便可

开始

建一个存放文档的 docs 目录,进入 docs 目录执行: sphinx-quickstart

填写信息的按本身的清空填写便可,有两个插件在安装过程当中须要启用:

• autodoc: automatically insert docstrings from modules (y/n) [n]: y 很重要，输入y

• viewcode: include links to the source code of documented Python objects (y/n) [n]: y 很重要，输入y，表示将源码也放到文档中，你看不少python的模块的文档，其实都是包含代码的。

修改配置文件 conf.py

• 设置要处理的路径(注1): sys.path.insert(0, os.path.abspath('..'))
• 若是前面的该启用的插件没用启用,能够在这里手动启用一下

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.coverage",
    "sphinx.ext.doctest",
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
]

生成所需的 rst 文档

返回 docs 目录的上一级,对当前目录的每个文件夹及子文件夹生成一个rst文件，对应python的包，存放在./docs目录下:

sphinx-apidoc -o ./docs/ .

注意:

• 这里第一个路径要和注1一致
• 若是以前生成过,添加 -f 参数便可覆盖

生成 HTML

进入 docs 目录,执行命令:make html

注意

• 代码中的执行要用下面的判断包装一下,不然可能致使 sphinx 等待代码执行,或者直接不动

if __name__ == '__main__':
    pass

• 若是代码中有自定义的包的路径,也要在配置文件中添加, sys.path.append("path") 便可
• 若是路径中包含 modules 字样的可能有问题

参考了: https://blog.csdn.net/suzyu12345/article/details/52923464