利用Sphinx为python项目生成文档

2020-12-14 10:36:32 编辑 0 阅读量:402

Sphinx最初是为python而产生的，用于生成新的python官方文档, 现可支持其它语言.

使用教程如下：
## 1. 安装Sphnix:
  `$ pip3 install Sphinx`

## 2. 为项目生成文档(sphinx支持从 .py代码提取docstring来生成文档)
```
$ cd myproject  # 如果项目有虚拟环境，则要进入虚拟环境
$ ls # 这里假设apps/目录包含一个文件, myapi.py
a.py    b.py    c.py  apps/
$  sphinx-quickstart docs/    # 要指定目录，否则会在当前目录生成一大堆东东
> autodoc: automatically insert docstrings from modules (y/n) [n]: y  # 必填
# 其它项都选择默认
# 完成之后，会在当前目录创建 docs/ 目录. 所有sphinx相关的文件都在 docs/目录下

$ ls docs/    # 之后仅要修改config.py, index.rst
_build  conf.py  index.rst  Makefile  _static  _templates
```

## 3. 修改配置，并从项目中读取docstrings
```
$ vi docs/conf.py
sys.path.insert(0, os.path.abspath('..'))   #　**IMPORTANT**  缺少此行会导致在make html时提示 __import__出错. 所以必须把上一级目录(即代码所在目录)include进来，一定要修改

$ sphinx-apidoc -o docs/ .    # 生成apidoc
Creating file docs/a.rst.
Creating file docs/modules.rst

# 把生成的 doc/modules.rst添加到index.rst
$ vi doc/index.rst

Contents:
 .. toctree::
    :maxdepth: 2

modules.rst

# 生成html页面
$ cd docs
$ make html
```

## 4. 可以添加自己想要的内容
基本的操作上面3步就可以完成，在这里可以添加自己想要的信息，比如：主要API的说明
```
$ vim docs/index.rst

API
============

重要API
------------
.. automodule:: apps.myapi
    :members:
    :undoc-members:
    :show-inheritance:
```
automodule 按目录层级来填, 然后重新生成文档
```
$ cd docs
$ make html
```

## 5. 修改主题
自带的主题有点丑丑的，所幸可以很简单的添加主题
```
$ pip install sphinx_rtd_theme
$ vim docs/conf.py  # 添加下面三行就够了
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme" 
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

$ cd docs    # 重新生成html就好了
$ make html
```

## 备注
1. sphinx生成的文档段内换行和普通的不太一样，要空一行才能换行，解决办法如下：
参数前加个":"
![](https://cblog.xyz/media/2018/03/TIM截图20180327155138.png)

参考
----
- [1][利用Sphinx为python项目生成文档](https://www.douban.com/note/510182448/)
- [2][sanic的说明文档（用来参考）](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html)
- [3][reStructuredText(rst)快速入门语法说明](https://www.cnblogs.com/seayxu/p/5603876.html)
- [4][sphinx快速入门](https://segmentfault.com/a/1190000007233355)
- [5][sphinx自动化文档](https://blog.csdn.net/suzyu12345/article/details/52923464)

利用Sphinx为python项目生成文档

附件: