快速上手

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

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

本文档的目的是让您快速了解什么是 Sphinx 以及如何使用 Sphinx。之后，您可以查看 安装指南，后面是关于 Sphinx 使用的默认标记格式的 reStucturedText 的介绍。

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

设置文档源目录

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

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

$ sphinx-quickstart

定义文档结构

让我们假设你运行 sphinx-quickstart。它创建了一个带有配置文件 conf.py 和一个根文件 index.rst 的源目录。根文件 的主要功能是作为一个欢迎页，并包含 toctree。这也是 Sphinx 为 reStructuredText 增加的主要内容之一，一种将多个文件链接到一个单一层次的文件。

reStructuredText 指令

toctree 是一个 reStructuredText 指令，一个非常通用的标记。指令可以有参数、选项和内容。

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

选项 以“字段列表”的形式跟在参数后面。maxdepth 就是 toctree 指令的一个选项。

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

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

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

.. toctree::
   :maxdepth: 2

您在指令的 内容 中添加列出它们的文档：

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

这正是本文档的 toctree 的样子。要包含的文档以 文档名 形式给出，简而言之，这意味着您无需使用文件扩展名并使用正斜杠（/）作为目录分隔符。

阅读更多关于 toctree 指令。

现在可以创建在 toctree 中列出的文件并添加内容，并且它们的部分标题将插入到放置 toctree 指令的位置（最高到 maxdepth 级别）。此外，Sphinx 现在知道文档的顺序和层次结构。（它们本身可能包含 toctree 指令，这意味着您可以在必要时创建深度嵌套的层次结构。）

添加内容

在 Sphinx 源文件中，您可以使用标准的 reStructuredText 的大部分功能。Sphinx 还添加了一些功能。例如，您可以使用 ref 角色以可移植的方式（适用于所有输出类型）添加跨文件引用。

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

待处理

当我们添加新指南时，请更新以下链接。

有关 reStructuredText 的更深入介绍，请参阅 reStructuredText，这里面包括 Sphinx 添加的标记。

运行 build

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

$ sphinx-build -b html sourcedir builddir

其中 sourcedir 是 源目录，builddir 是您要在其中放置构建文档的目录。-b 选项选择一个构建器；在这个例子中，Sphinx 将构建 HTML 文件。

参考 sphinx-build 手册 以了解 sphinx-build 支持的所有选项。

但是，sphinx-quickstart 脚本创建了一个 Makefile 和一个 make.bat，它让你的生活更加轻松。这些可以通过运行 make 来执行，其中包含构建器的名称。例如：

$ make html

这将在您选择的构建目录中构建 HTML 文档。执行 make 不带参数来查看哪些目标可用。

如何生成 PDF 文档？

make latexpdf 运行 LaTeX builder 并且很容易为你调用 pdfTeX 工具链。

待处理

将整个部分移动到有关 rST 或指令的指南中

文档对象

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

   ...

如果您保留默认域的默认设置，则执行相同的工作。

还有几个指令用于记录其他类型的 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 源文件执行，您可以分配配置值。对于高级用户：由于它是由 Sphinx 执行的，因此您可以在其中执行非平凡的任务，例如扩展 sys.path 或导入模块以找出您正在记录的版本。

您可能想要更改的配置值已经放入 conf.py 由 sphinx-quickstart 并且最初被注释掉（使用标准的 Python 语法: # 注释其余的这行）。要更改默认值，请删除 # 并修改该值。要自定义一个不会自动添加的配置值 sphinx-quickstart，只需添加一个额外的赋值。

请记住，该文件使用 Python 语法来表示字符串，数字，列表等。默认情况下，文件以 UTF-8 保存，如第一行中的编码声明所示。

阅读 配置 了解配置值的更多信息。

待处理

将整个文档移动到不同的部分

Autodoc

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

为了使用 autodoc，你需要在 conf.py 中激活它，方法是将字符串 'sphinx.ext.autodoc' 放入分配给 extensions 配置的列表中值:

extensions = ['sphinx.ext.autodoc']

然后，您可以使用其他一些指令。例如，要记录函数 io.open()，从源文件中读取它的签名和 docstring，你就写下:

.. autofunction:: io.open

您还可以使用 auto 指令的成员选项自动记录整个类甚至模块，例如:

.. automodule:: io
   :members:

autodoc 需要导入您的模块才能提取文档字符串。因此，您必须在 conf.py 中添加适当的路径 sys.path。

警告

autodoc 导入 所有需要自动生成文档的模块。如果某些模块在导入时有一些额外的操作，在运行 sphinx-build 时，也会被 autodoc 执行。

如果你要引入脚本（而不是库模块），确保主程序 main 有这个条件保护着：if __name__ == '__main__'。

关于 autodoc 的完整功能请查阅：sphinx.ext.autodoc。

待处理

将此文档移到另一部分

跨 Sphinx 引用

包括 Python 文档 在内的许多 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 中配置的文档集中查找（这需要访问 URL 以下载有效目标列表）。Intersphinx 也适用于其他一些 域 的角色，包括 :ref:，但它不适用于 :doc: 因为那是非域角色。

完整的跨 Sphinx 引用的功能介绍，参考 sphinx.ext.intersphinx。

其他常用功能举例

• 其他插件:

• 静态文件

• 选择主题

• Setuptools integration

• 使用模板

• 使用插件

• 编写插件

脚注

1

这是通常的设置。然而，conf.py 也可以在其他的目录中，即 配置目录。更多信息请参考 sphinx-build 手册。