开始

Sphinx 是一个 文档生成器 ，您也可以把它看成一种工具，它可以将一组纯文本源文件转换成各种输出格式，并且自动生成交叉引用、索引等。也就是说，如果您的目录包含一堆 reStructuredText 或 Markdown 文档，那么 Sphinx 就能生成一系列HTML文件，PDF文件（通过LaTeX），手册页等。

Sphinx 专注于文档，尤其是 handwritten documentation ，然而，Sphinx 也可以用来生成博客、主页甚至书籍。Sphinx 的大部分功能来自于 reStructuredText ，它是一种纯文本标记格式，有着丰富的功能和 significant extensibility capabilities 。

本文档的目标是让您快速了解 Sphinx 以及如何使用它。阅读完本文档后，您可以查看 安装指导 ，然后是 Sphinx 使用的默认标记格式 reStructuredText 。

如果你想了解如何撰写文档，请参考 Eric Holscher 写的 撰写文档 。

初始化文档源目录

Sphinx 文档有一个根目录，里面存放着很多纯文本格式的源文件，这个根目录称为 source directory 。该目录还包含 Sphinx 配置文件 conf.py ，您可以在其中指定 Sphinx 如何读取源代码和生成文档。[1]

Sphinx 附带一个名为 sphinx-quickstart 的脚本，这个脚本会设置一个源目录并创建一个默认的 conf.py 配置文件，在创建时，它还会问你一些问题，并从中得到配置值填入配置文件中。要使用此脚本，请运行：

$ sphinx-quickstart

定义文档结构

假设您已经运行了 sphinx-quickstart 。它创建了一个包含 conf.py 和根文档 index.rst 的源目录。root document 的主要功能是作为欢迎页面，并且包含“目录树”（或 toctree ）的根节点。这是 Sphinx 为 reStructuredText 添加的主要功能之一，它可以将多个文件连接到单个文档层次结构中。

reStructuredText 指令

“toctree” 是一个 reStructuredText 指令 ，即具有特殊功能的标记。指令可以有参数、选项和内容。

参数 可以直接跟在指令的的两个英文冒号后面。不同指令有不同数量的参数，亦或没有。

选项 以“字段列表”的形式跟在参数后面。“maxdepth”（意为“（目录层级的）最大深度”）就是 “toctree”指令的一个选项。

内容 跟在选项或参数后面，它和选项/参数之间要空一行。每个指令决定是否允许内容，以及如何处理内容。

指令的一个常见问题是 内容的第一行必须缩进到与选项相同的级别 。

toctree 指令最初是空的，看起来像这样：

.. toctree::
   :maxdepth: 2

您可以在指令的 内容 处列出要添加的文档：

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

这正是本文档的 toctree 的外观。要包含的文件以 document name 的形式给出，简单来说就是你不使用文件扩展名并使用正斜杠(/)作为目录分隔符。

参见

阅读更多关于 toctree 指令 的内容。

现在你可以创建刚刚列在 toctree 里的文件，并添加内容了，它们的标题会（按照 maxdepth 设置的深度）自动插入到文档中的 toctree 指令的位置。而且 Sphinx 也知道你文档的顺序和层级结构。（文档自身也可以包含 toctree 指令，这样在需要的时候，就可以创建更深的嵌套层级了）

添加内容

在 Sphinx 源文件中，您可以使用标准 reStructuredText 的大部分功能。不过也有一些功能是 Sphinx 独有的。比如，你可以使用 ref 角色来方便地添加跨文件的引用（对于所有输出格式都可用）。

例如，如果您正在查看HTML版本，则可以查看此文档的源代码——使用侧栏中的“显示源代码”链接。

参见

reStructuredText 提供了对 reStructuredText 的更深入介绍，包括 Sphinx 添加的标记符号。

运行生成程序

现在您已经添加了一些文件和内容，现在让我们构建文档吧。使用 sphinx-build 程序启动构建：

$ sphinx-build -M html sourcedir outputdir

其中 sourcedir 是 source directory ，outputdir 是您想要放置生成文档的目录。选项 -M 用于选择生成器；在此示例中，Sphinx 将生成 HTML 文件。

参见

所有 sphinx-build 支持的选项，参考 sphinx-build man page 。

你也可以构建一个可以在浏览器中审阅的 实时版本的文档。它将会检查源文件的变化，每次你编辑源文件时，都会重载网页。使用 sphinx-autobuild 来运行下述命令即可：

$ sphinx-autobuild source-dir output-dir

但是， sphinx-quickstart 脚本创建了一个 Makefile 和一个 make.bat ，它给你提供了更多便利。 它们可以通过 make 命令执行，后面带有生成器的名称。例如：

$ make html

这将在您选择的生成目录中生成 HTML 文档。 执行不带参数的 make 命令，以查看可用的生成目标。

如何生成 PDF 文档？

执行“make latexpdf”即可调用 LaTeX builder 并且自动帮你调用 pdfTeX 工具链。

给对象写文档

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

返回一个迭代器，它生成包含索引和 sequence 中元素的元组。（等等）

指令的参数就是你要描述的对象的签名 ( signature ) ，而内容就是针对它的文档。可以给出多个对象签名，分开写就可以，一行写一个。

恰好 Python 域是默认的域，所以不需要再另外写前缀。

.. function:: enumerate(sequence[, start=0])

   ...

效果就是一样的（如果你没有改动默认域的设置）。

还有一些指令用于给其他类型的 Python 对象写文档，例如 py:class 或 py:method 。对于每种对象类型，都有一个用于交叉引用 角色 。这个标记将创建一个指向“enumerate()”文档的链接。

The :py:func:`enumerate` function can be used for ...

效果就是这样：一个指向 enumerate() 的链接。

再强调一次，如果 Python 域是默认域的话，就可以省略不写 py:。不管 enumerate() 的文档在哪个文件中，Sphinx 都会自动找到它，并且创建指向它的链接。

每个不同的域都有它对签名的要求，以使得生成的文档好看，也有各自的特定功能，比如 C/C++ 域中可以链接到参数类型。

参见

域 提供了所有可用域及其指令/角色的介绍。

基本配置

之前我们提到，在文件 conf.py 中，可以控制 Sphinx 如何处理你的文档。它是一个 Python 源文件，你可以给相应的变量赋值。对于高级用户来说，因为它是可以执行的程序，你可以做一些更高级的任务，比如扩展 sys.path 或者导入代码模块并检查源程序的版本。

你想要配置的参数很可能已经包含在由 sphinx-quickstart 生成的 conf.py 中，并且默认被注释掉了（就是标准的 Python 语法，行首加 # 就把这一行后面的内容注释掉了）。要改变默认值的话，就把前面的井号键删掉然后再修改默认值。要是想添加自己的配置，就是不由 sphinx-quickstart 自动生成的配置的话，只需要自己添加别的赋值语句就行。

要记得，这个文件要使用 Python 语法写字符串、数字、列表等。此文件默认使用 UTF-8 编码，而且写在文件的第一行了。

参见

配置 提供了所有可用配置值的文档说明。

使用 autodoc 自动生成文档

给 Python 代码写文档的一种常见做法是，在 Python 源文件里以文档字符串的形式在代码中插入文档。使用 autodoc 扩展程序 （扩展程序是给 Sphinx 项目提供更多的功能的 Python 模块），Sphinx 就可以把你模块中的文档字符串插入进来。

参见

sphinx.ext.autodoc 提供了 autodoc 功能的完整描述。

跨 Sphinx 引用

包括 Python documentation 在内的许多 Sphinx 文档都在互联网上发布。如果要从文档中链接到此类文档，可以使用 sphinx.ext.intersphinx 。

要使用 intersphinx，需要在 conf.py 文件中配置 extensions 变量，把字符串 'sphinx.ext.intersphinx' 附加到列表，还要设置参数 intersphinx_mapping。

比如，要链接到 Python 库官方文档的 io.open() ，要对 intersphinx_mapping 进行如下配置

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

现在你就可以使用像 :py:func:`io.open` 这样的交叉引用了。对于在当前文档中匹配不到的交叉引用，就会到配置的 intersphinx_mapping 跨 Sphinx 文档列表中查找（这需要能够访问到相应的 URL 以便下载可用文档对象的列表）。跨 Sphinx 引用也可以用于其他 domain 相关的文本角色，比如 :ref: ；但不包括 :doc: 等不支持域的文本角色。

参见

sphinx.ext.intersphinx 提供了 intersphinx 功能的完整描述。

其他常用功能举例

脚注