python sphinx 自动化文档的用法
2018-08-29 17:19
351 查看
安装
直接使用 pip3 install sphinx 即可开始
建一个存放文档的 docs 目录,进入 docs 目录执行: sphinx-quickstart填写信息的按自己的清空填写即可,有两个插件在安装过程中需要启用:
autodoc: automatically insert docstrings from modules (y/n)
: y 很重要,输入y
viewcode: include links to the source code of documented Python objects (y/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
相关文章推荐
- python自动生成易于阅读的html文档——使用Sphinx
- Sphinx将python代码注释生成文档
- Python Scapy(2.3.1)文档学习(四):高级用法
- 使用Sphinx为你的python模块自动生成文档
- Python让繁琐工作自动化——chapter13 处理PDF和Word文档
- python sphinx 文档自动生成方法
- [Dynamic Language] 用Sphinx自动生成python代码注释文档
- sphinx根据python注释生成文档
- CrazyWing:Python自动化运维开发实战 二十一、html标签用法平推式
- python自动生成易于阅读的html文档——使用Sphinx
- 【Python】使用 sphinx 制作简洁而又美观的文档
- 使用sphinx快速生成Python API 文档
- Sphinx将python代码注释生成文档
- Sphinx--python模块自动生成文档
- CrazyWing:Python自动化运维开发实战 二、Python基本用法
- 使用sphinx自动提取python中的注释成为接口文档
- Python写自动化之使用sphinx提取Python代码docstring
- 使用Sphinx为你的python模块自动生成文档
- 利用Sphinx轻松生成python代码的文档