入门

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

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

The goal of this document is to give you a quick taste of what Sphinx is and how you might use it. When you’re done here, you can check out the installation guide followed by the intro to the default markup format used by Sphinx, reStructuredText.

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

初始化文档源目录

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

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

$ sphinx-quickstart

定义文档结构

Let’s assume you’ve run sphinx-quickstart. It created a source directory with conf.py and a root document, index.rst. The main function of the root document is to serve as a welcome page, and to contain the root of the “table of contents tree” (or toctree). This is one of the main things that Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.

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

.. toctree::
   :maxdepth: 2

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

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

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

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

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

添加内容

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

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

待处理

在我们添加新指南时更新以下链接。

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

运行生成程序

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

$ sphinx-build -M html sourcedir outputdir

where sourcedir is the source directory, and outputdir is the directory in which you want to place the built documentation. The -M option selects a builder; in this example Sphinx will build HTML files.

更多信息 请参阅 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.)

指令的参数就是你要描述的对象的签名 ( 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++ 域中可以链接到参数类型。

更多信息 See 域 for all the available domains and their directives/roles.

基本配置

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

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

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

更多信息 如果想了解所有的配置数据，请参考 配置。

待处理

将整个文档移动到其他部分

使用 autodoc 自动生成文档

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

要使用 autodoc ，先要在 conf.py 文件中启动它。在配置参数 extensions 的列表中，添加一个字符串 'sphinx.ext.autodoc' 即可:

extensions = ['sphinx.ext.autodoc']

然后，您可以使用其他一些指令。比如，要导入函数 io.open() 的文档，包括其在源代码文件当中的函数签名、文档字符串等，您要这样写:

.. autofunction:: io.open

你也可以自动导入整个类甚至整个模块的文档，使用 member 选项，如下所示

.. automodule:: io
   :members:

autodoc needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to sys.path in your conf.py.

警告

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 跨 Sphinx 文档列表中查找（这需要能够访问到相应的 URL 以便下载可用文档对象的列表）。跨 Sphinx 引用也可以用于其他 域 相关的文本角色，比如 :ref: ；但不包括 :doc: 等不支持域的文本角色。

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

其他常用功能举例

脚注