sphinx入门指南【1】快速入门

简介

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还格外提供了一些指令。

具体可以参考

reStructuredText Primer 以及
Sphinx Markup Constructs

生成文档

使用下面的命令生成文档：

$ 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()]