利用Sphinx自动生成Python项目文档之一初探

sphinx doc 2016年08月24日 星期三

之前有纠结过怎么才能很好的管理项目的文档,有写过doc、md,以及confluence,这些都算是手工写出来的文档,维护起来还是相对比较麻烦,几乎都会出现一种现象就是文档一出就会很少去维护,修改添加==。

接触到sphinx之后,它能快速自动生成简单、漂亮的文档,导出html或者其他样式。

安装sphinx

pip install Sphinx

在需要创建文档项目的地方执行,快速生成文档目录以及相依的配置文件,如: doc

sphinx-quickstart

修改对应项目python path: 如:doc/conf.py

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

快速在doc下生成文档,即项目各个模块的rst文件,当新加目录的时候需要重新执行

sphinx-apidoc -o ./doc/ .

进入doc目录生成Html文档,根据各个模块的rst进行生成html

make html

这时候就会在doc目录下有个_bulid/html/,在网页中打开index.html,简明、漂亮的文档就有了。

------------- 2016.12.21补充

今天看了下sphinx的各个theme, 可以进行选择比如【官方主题信息】,感觉都很棒,但看着最下面推荐的第三方sphinx_rtd_theme,的确蛮不错哦。配置也很简单。之后再运行make html 就重新生成文档。

# 安装依赖库
# pip install sphinx_rtd_theme
# 在对应的conf.py 中添加
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]