sphinx为python项目创建说明文档——快速入门

[leeduckgo]

作者：王宁波

1 安装

---

pip install sphinx

2 创建一个sphinx项目,并解读核心文件

---

举例:

在docs文件夹下创建一个sphinx项目

在命令行中，进入到docs目录之后，用下面的命令即可创建完成

sphinx-quickstart

接下来会让你输入项目名，作者名，版本号，语言（中文是zh_cn）

最后你会发现docs下出现了两个文件夹和两个文件

因为是入门，我们主要关心source这个文件夹下的东西

1.是conf.py这个文件，里面主要是配置描述项目的东西

需要我们修改的是:

（1）.让sphinx找到你的python项目路径，注意路径是相对路径

下面这段代码被注释了，可打开，传入你的项目路径
import os

import sys

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

（2）可为extensions添加一个参数，自动生成文档

extensions = ['sphinx.ext.autodoc']

（3）可指定文档页面的主题，可以使用sphinx内置的，也可使用以下代码，但是还要（pip install spxinx_rtd_theme）
html_theme = 'sphinx_rtd_theme'

2.index.rst这个文件，主要是渲染index.html这个首页的内容，不改也没事

3生成每个python模块对应的.rst文件

---

执行下面代码，注意-o后面传的两个路径（相对路径），分别用空格隔开

sphinx-apidoc -o index.rst所在目录 python项目所在目录

4 最后生成每个模块对应的html

---

make html

5 常见错误

---

1.windows默认是没有make这个命令的，这时就去下载MinGW,无脑安装，选择下载组件时，选择mingw32-base-bin一个就够了,
打开all packages检查一下mingw32-make-bin是否被选上，没有的话请选上，然后点击菜单栏installation—apply changes等待下载完成，
可能很慢很慢，安装过程中如果出现某些包download错误，点击确认即可下载完成后，把mingw32-make.exe改成make.exe,然后把你下载的MinGW
这个目录下的bin目录设置一下环境变量，就能像别的系统一样使用make 命令了

2.如果你的系统支持以上操作，但是报错了或者文档展示有问题，那很有可能配置conf.py错误，路径一定看清楚