简介
sphinx是一个用于快速生成文档的工具，非常适合生成Python文档。
它具有以下优点：
- 支持多种输出格式， 如html，Latex，ePub等。
- 丰富的扩展
- 结构化文档
- 自动索引
- 支持语法高亮
sphinx使用reStructuredtext作为它的标记语言。
安装
使用pip进行安装：
pip install sphinx
设置源文件目录
包含.rst文件的根目录称之为源文件目录，目录中还包含sphinx的配置文件conf.py。
进入源文件目录，执行以下命令，会指引用户配置整个项目：
sphinx-quickstart
定义文件结构
执行上述命令之后，sphinx会在源文件目录中自动生成conf.py文件以及index.rst。index.rst称之为主文档，它被sphinx作为欢迎页面。
index.rst中包含了目录树指令toctree，sphinx使用它链接其他子文档。
toctree指令的初始值为空：
.. toctree::
:maxdepth: 2
接下来就可以给它添加子文档的链接了，直接使用文档的名称即可，省略掉文件后缀，如果是多级目录，则使用/分隔开。
.. toctree::
:maxdepth: 2
intro
tutorial
chapter/doc1
...
接着我们就可以创建上面列出的文件并添加相应内容了，sphnix会自动将这些文档的章节标题插入到doctree指令的位置。
添加内容
在sphinx源文件中，使用reStructuredText标记语言进行文档编写，除此之外，sphinx还格外提供了一些指令。
具体可以参考
生成文档
使用下面的命令生成文档：
$ sphinx-build -b html sourcedir builddir
sourcedir指源文件目录，生成的文档放置在builddir指定的目录中。
实际上还有一个更简便的方法，sphinx-quickstart生成了一个make.bat文件，可以直接运行这个脚本：
make html
上述命令会直接在源文件目录中生成文档。
对象文档
sphinx的设计初衷之一就是更容易生成任何域中对象的文档，域指很多对象的集合，这些对象中还包含了相应的文档注释。
最主要的域是Python域， 例如python内置函数enumerate()的注释文档如下所示：
.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)
它将被渲染成如下格式：
enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)
指令参数是我们需要描述的对象，内容是我们编写的文档注释。由于Python是默认的域，所以并不需要特别指出所属的域来。
.. function:: enumerate(sequence[, start=0])
...
sphinx还提供了一些指令用于生成其他对象类型的文档。例如py:class以及py:method
基本配置
sphinx通过conf.py进行配置，conf.py使用python语法，默认以utf-8编码保存。具体配置请查看 The build configuration file。
自动生成文档注释
sphinx支持从python源代码中提取文档注释信息，然后生成文档，我们将这称之为autodoc。
为了使用autodoc，首先需要在配置文件的extensions选项中添加'sphinx.ext.autodoc'。然后我们就可以使用autodoc的指令了。
例如，生成函数io.open()的文档，只需要在rst文件中添加如下语句：
.. autofunction:: io.open
也可以直接生成整个类的文档：
.. automodule:: io
:members:
为了提取文档注释，autodoc需要导入注释所在的模块。因此需要在sys.path中设置好模块的路径。
设置主题
推荐使用readthedoc使用的主题，美观又简洁大方。
首先安装主题库：
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()]
网友评论