Question

Sphinx 是一款文档编辑工具，具有十分全面的文档资料。

Sphinx 官方网站

http://www.sphinx-doc.org/en/stable/

Sphinx 使用手册

http://www.sphinx-doc.org/en/stable/contents.html

本节将对以下各项进行简要说明。

· Sphinx 的安装

· reStructuredText 入门

· 用 Sphinx 编写结构化文档的流程

· Sphinx 扩展

7.2.1　Sphinx 的安装

Sphinx 的安装流程并不复杂，但各位要尽量使用最新版本。这里建议各位使用最新的 Sphinx-1.3 系列（截至 2014 年 12 月时的最新版本）。

安装用以下命令执行。

$ pip install sphinx

这样，我们就装好了 Sphinx 关联的程序包，现在可以用 sphinx-quickstart 命令了。sphinx-quickstart 命令能自动生成启动 Sphinx 所需的数个文件。具体执行方法如 LIST 7.1 所示。

LIST 7.1　sphinx-quickstart

$ sphinx-quickstart -q -p SW-Project -a BeProud -v 1.0 sw-project
Creating file sw-project/conf.py.
Creating file sw-project/index.rst.
Creating file sw-project/Makefile.
Creating file sw-project/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file sw-project/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
$ ls sw-project/
_build  conf.py  index.rst  make.bat  Makefile  _static  _templates

执行完毕后，sw-project 目录下就生成了 Sphinx 项目，然后就可以通过 make html 构建 Sphinx 了。Sphinx 写文档的标准扩展名为“.rst”，所以这里会生成 index.rst 文件。

如果不加任何选项直接执行 sphinx-quickstart ，则会以对话形式生成 Sphinx 项目。这种情况下，计算机将以对话形式提出几项询问，其中 Project Name、Author、Version 这 3 个问题需要由我们来输入，其他问题则只需根据实际情况选择 Y 或 N 即可。在 LIST 7.2 的例子中，我们让文件生成在 sw-project 目录下。

LIST 7.2　sphinx-quickstart 对话模式

$ sphinx-quickstart
Welcome to the Sphinx 1.3 quickstart utility.
-（中间省略）-
> Root path for the documentation [.]: sw-project
-（中间省略）-
> Project name: SW-Project
> Author name(s): BeProud
-（中间省略）-
> Project version: 1.0
-（中间省略）-
$ ls sw-project
_build  conf.py  index.rst  make.bat  Makefile  _static  _templates

通过 sphinx-quickstart 设置的内容全都记录在 conf.py 文件中，所以日后想更改设置时需要编辑 conf.py 文件。另外，如果想用中文版的 Sphinx，可以在 conf.py 文件中作如下设置（LIST 7.3）。

LIST 7.3　conf.py

language = 'zh_CN'

详细安装流程以及 Sphinx 的初始设置请参考以下网站。

Sphinx 入门

http://www.sphinx-doc.org/en/stable/install.html

7.2.2　reStructuredText 入门

Sphinx 要用 reStructuredText（reST）语法写文档。这里我们学习几个具有代表性的 reST 写法（LIST 7.4）。

LIST 7.4　sample.rst

==============
章标题
==============
: 项目1：字段列表内容1
: 项目2：字段列表内容2
: 项目3：字段列表内容3
节标题1
=====================
节内第一个段落的文章。
换行会被忽略。
第二个段落的文章。
用空行划分段落。
空行至少为一行，输入多少行效果都一样。
1. 规定编号的有序列表
2. 规定编号的有序列表
  #. 自动编号的有序列表
  #. 自动编号的有序列表
没有编号的无序列表按以下格式书写。
* 无序列表
* 无序列表
  + 低一级的无序列表
  + 低一级的无序列表
可以给词汇添加多种特殊意义。
- ** 强调**
- * 斜体*
- `` 显示为字符串``
- ` 链接字符串A`_
- ` 链接字符串B<http://docs.sphinx-users.jp>`__
- :doc:`index` 到对象文件的链接。会自动替换为章标题。
.. _ 链接字符串A: http://sphinx-users.jp

为了从首页链接到这个 sample.rst 文件，我们在 index.rst 中作如下描述（LIST 7.5）。

LIST 7.5　index.rst

.. toctree::
   :maxdepth: 2
   sample

这样就可以构建 sample.rst 了。接下来我们执行 make html （LIST 7.6）。

LIST 7.6　make html

$ make html

构建结果将输出到“_build/html”目录下。用浏览器打开“_build/html/sample.html”可以看到如图 7.1 所示的输出结果。

图 7.1　Sphinx 输出示例

reStructuredText 入门

http://www.sphinx-doc.org/en/stable/rest.html

7.2.3　用 Sphinx 写结构化文档的流程

Sphinx 在很多地方都引入了结构化的概念，因此它为写文档的人提供了一个方便写文档且方便整理的环境。下面就是利用 Sphinx 提供的结构化来编写文档的流程。

◉ 标题与元素

我们从零开始写文档时，往往会不知从何写起。虽然想到什么写什么不失为一种办法，但最好还是先列出标题大纲，整理一下文档内容的结构（LIST 7.7）。

LIST 7.7　先逐条列出标题

* 标题1
  * 副标题1
  * 副标题2
* 标题2
* 标题3

然后再将想到的东西填进适当位置，使文章逐渐丰满起来（LIST 7.8）。

LIST 7.8　给标题添加内容

* 标题1
  * 副标题1
  * 副标题2
  * 副标题3
  在这里逐渐补充副标题3 的内容。
  如果想到了与副标题3 无关的内容，
  就补充到其他合适的地方。
* 标题2
  * 副标题1
  * 副标题2
* 标题3
  * 副标题1
  * 副标题2

这种具有明确父子关系或兄弟关系的文本称为结构化文本。本例中既用了标题和内容这种具有明显父子关系的逐条列记，又用了空格缩进的文本。在写文档时，如果我们脑中没有一个明确的框架，就需要不断重复这种堆砌“标题”与“表达内容的元素”（本例中是副标题）的工作。

◉ 单一文件内的结构化

用 reStructuredText 写的文章会被结构化，看上去条理分明。比如用 reStructuredText 描述会议记录并添加到邮件中，收件人就可以直接流畅地阅读。

结构化让各条信息之间的关系更加明确，并列、父子结构一目了然，而且信息的换位与重排也能很轻松地进行。

按照这种结构化规则写出的文本具有树结构（图 7.2）。

图 7.2　文本的树结构

◉ 文件与目录的结构化

在写文档的过程中，会遇到标题下的内容过于详细的情况，这会破坏文章的平衡性。另外，如果我们只往一个文件里写，文章的主干就会越来越模糊，事情也会越来越讲不清楚。当文章达到一定规模，其内容需要分类分割时，我们可以根据文件和目录将其分割并结构化。分割后，主干与分支之间必须保持一个父子关联。这样一来，文件就能在分割之后仍保持树结构了（图 7.3）。

图 7.3　在维持树结构的前提下分割文件

等到文件数量多起来，可以将文件分组，按目录进行结构化。总而言之，就是灵活运用文件与目录，不断将结构化向前推进。

先将文档的章或节按目录或文件进行分割，这有助于我们今后对章节进行增减与重排。另外，由于文件被分成了多个，所以可以 1 人或多人同时编辑多个地方。举个例子，如果我们同时想到好几个点，那么可以同时打开多个文件做记录，这要比编辑单一文件更容易找到信息的位置，而且能很轻松地定位到之前中断工作的地方。

Sphinx 能将所有文档文件组合到一个树结构中。这样，所有文件都被排成了一个序列，并以让人能从上至下阅读的格式进行输出。该定义需在文档中用 .. toctree:: 指令描述。

只要有了 toctree 这样一个主干，文档就能在被分割成多个文件之后仍保持其结构。

◉ 网状结构

只要按照一定的规则给文档加入关键字或到其他章节的跳转，就能实现 Wiki 那种灵活的网状结构。脚注、交叉引用、术语集、索引等就是此类网状结构（图 7.4）。

图 7.4　结构化文档的网状结构

链接可以让我们更容易地在文档中找到想找的信息。Sphinx 会为我们提供清晰的术语集、API 参考手册等信息，我们可以利用这个功能来统一术语。

比如在写文章的过程中发现有术语需要统一，我们可以先用 :term:` 术语 ` 的形式将该术语写下来。由于 Sphinx 在 make 时会提示该术语没有对应的术语说明，所以我们完全可以把写术语说明的工作放到最后再做，这样既不会打断写文章的进度，也不必担心出现遗漏。

此外，我们还可以用 :doc:`../sub/index` 这样的形式指定引用页面的相对路径，Sphinx 在 make 时会自动将该页面的标题和链接填充到这里。

◉ 结构化的 3 个阶段

正如我们前面所介绍的，结构化分为如下 3 个阶段（图 7.5）。

① 单一文件内的结构化

② 分割成多个文件 / 目录并结构化

③ 连接成无直接父子关系结构的网络

图 7.5　结构化的 3 个阶段

通过这样从内到外地让文章结构化、分组化，文档将自然而然地得到整理，写起来当然也会轻松许多。另外，Sphinx 以树结构为基础，与 Wiki 那种仅由网络形成的半格结构不同，阅读起来主次分明，易于理解。以树结构为主让文档整体有了一根脊梁，然后在各结构之间添加神经网络，这样可以加强文档阅读时的灵活性。

7.2.4　Sphinx 扩展

Sphinx 捆绑了 TeX 排版系统等扩展，另外也支持单独安装第三方开发的扩展。这些扩展包括流程图、序列图等图表的植入扩展、UML 画图、乐谱绘图、HTML 模板变更等。当然我们还可以自己开发扩展。

扩展功能在 Sphinx 的 conf.py 文件中设置。比如我们可以像 LIST 7.9 这样描述。

LIST 7.9　conf.py

extensions = ['sphinx.ext.pngmath', 'sphinx.ext.todo', 'sphinx.ext.autodoc',]

这样就激活了 Sphinx 主体程序自带的 3 个扩展功能。这里将介绍的是 sphinx.ext.pngmath。

pngmath 扩展用来在文档中以图片形式显示数学公式。我们只要在文档中描述了代表数学公式的字符串，该扩展就会在构建时将它们转换为 PNG 图像文件植入文档。不过，用这个扩展的前提是具备 LaTeX 环境 2 。

2 Sphinx-users.jp 网站上有介绍 LaTeX 环境的安装流程。——编者注

我们在文档中作如下描述（LIST 7.10）。

LIST 7.10　math.rst

=======
数学公式
=======
.. math:: (a + b)^2 = a^2 + 2ab + b^2

构建之后会显示如图 7.6 所示的数学公式。

图 7.6　sphinx.ext.pngmath 的数学公式绘图

Sphinx 对数学公式的支持

http://www.sphinx-doc.org/en/stable/ext/math.html

经由LaTeX 输出PDF 文档3 （日语）

http://sphinx-users.jp/cookbook/pdf/latex.html

3 该部分内容是 Sphinx-users.jp 网站针对日语文档的生成这种情况而编写的。英语文档的生成则参照 Sphinx 手册即可。——编者注