使用Sphinx为你的python模块自动生成文档

# 前言

Sphinx是一个可以用于Python的自动文档生成工具，可以自动的把docstring转换为文档，并支持多种输出格式包括html，latex，pdf等。

安装

pip install sphinx

创建一个sphinx项目

下面的命令会自动生成一个默认的Sphinx模板

mkdir yourdir
cd yourdir
sphinx-quickstart

执行期间，它会一步步的询问对模板的设置，除了一些必须填写的选项，大部分填写默认值就行了，你会遇到这样一条叫autodoc的，需要选择yes

autodoc: automatically insert docstrings from modules (y/n) [n]

然后默认的目录就生成了，大概是这个样子

- yourdir/ # 刚才新建的目录
    - source/ # 存放Sphinx工程源码
    - build/ # 存放生成的文档
    Makefile

现在执行如下指令，就会生成一份空文档，存放在/build/html里，点击index.html就可以打开一个空的网页，虽然没有内容，但是整体的结构还是在的

sphinx-build -b html source build
make html

source/ 目录

source/目录里有两个文件，分别是conf.py和index.rst，下面对它们进行进一步的介绍

index.rst

.rst是reStructuredText，和Markdown一样是一种标记语言，具体的语法可以看这里 reStructuredText Primer。
实际上，我们在使用Sphinx的过程中最主要就是对这些rst文件进行修改，而Sphinx所做的事情就是读取这些rst文件，