入门¶
Sphinx 是一个文档生成器或一个工具，它将一组纯文本源文件转换为各种输出格式，自动生成交叉引用、索引等。也就是说，如果你有一个目录包含一堆reStructuredText或Markdown文档，Sphinx 可以生成一系列 HTML 文件，一个 PDF 文件（通过 LaTeX），man 页面等等。
Sphinx 专注于文档，特别是手写文档，但是，Sphinx 也可以用于生成博客、主页甚至书籍。Sphinx 的很大一部分力量来自于它丰富的默认纯文本标记格式，reStructuredText，以及它的显著的扩展能力.
本文档的目的是让你快速了解 Sphinx 是什么以及你如何使用它。当你完成这里的内容后，你可以查看安装指南，然后是 Sphinx 使用的默认标记格式的介绍，reStructuredText.
有关一般文档写作的精彩“介绍” - 为什么和怎么做，还可以参考 Eric Holscher 编写的Write the docs.
设置文档源¶
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 中列出的文件并添加内容，它们的章节标题将插入（最多达到 maxdepth 级别）在放置 toctree 指令的位置。此外，Sphinx 现在了解您文档的顺序和层次结构。（它们可能包含 toctree 指令本身，这意味着您可以创建深度嵌套的层次结构，如果需要的话。）
添加内容¶
在 Sphinx 源文件中，您可以使用标准 reStructuredText 的大多数功能。Sphinx 还添加了一些功能。例如，您可以使用 ref 角色以可移植的方式添加跨文件引用（适用于所有输出类型）。
例如，如果您正在查看 HTML 版本，您可以查看本文档的源代码 - 使用侧边栏中的“显示源代码”链接。
另请参阅
reStructuredText 提供了对 reStructuredText 的更深入介绍，包括 Sphinx 添加的标记。
运行构建¶
现在您已经添加了一些文件和内容，让我们构建第一个文档。构建使用 sphinx-build 程序启动
$ sphinx-build -M html sourcedir outputdir
其中sourcedir是源目录，outputdir是您要放置构建的文档的目录。-M 选项选择一个构建器；在这个例子中，Sphinx 将构建 HTML 文件。
另请参阅
参考sphinx-build 手册页了解 sphinx-build 支持的所有选项。
但是，sphinx-quickstart 脚本创建了一个 Makefile 和一个 make.bat，它们使您的生活更加轻松。这些可以通过运行带有构建器名称的 make 来执行。例如。
$ make html
这将在您选择的构建目录中构建 HTML 文档。执行不带参数的 make 以查看可用的目标。
如何生成 PDF 文档？
make latexpdf 运行LaTeX 构建器，并立即为您调用 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])¶
返回一个迭代器，它会产生序列的索引和项目的元组。（等等。）
指令的参数是您描述的对象的签名，内容是它的文档。可以给出多个签名，每个签名占一行。
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 或导入一个模块来查找您正在记录的版本。
您可能想要更改的配置值已经由 sphinx-quickstart 放入 conf.py 中，并且最初被注释掉了（使用标准的 Python 语法：# 注释掉该行后面的内容）。要更改默认值，请删除井号并修改该值。要自定义 sphinx-quickstart 没有自动添加的配置值，只需添加一个额外的赋值即可。
请记住，该文件使用 Python 语法来表示字符串、数字、列表等。该文件默认情况下以 UTF-8 编码保存，如第一行中的编码声明所示。
另请参阅
配置 文档列出了所有可用的配置值。
Autodoc¶
在记录 Python 代码时，通常会在源文件中使用文档字符串来放置大量文档。Sphinx 支持使用名为“autodoc”的扩展（扩展是一个 Python 模块，为 Sphinx 项目提供额外的功能）来包含来自模块的文档字符串。
另请参阅
sphinx.ext.autodoc 提供了 autodoc 功能的完整描述。
Intersphinx¶
许多 Sphinx 文档（包括 Python 文档）都在互联网上发布。当您想要从您的文档中链接到这些文档时，可以使用 sphinx.ext.intersphinx。
为了使用 intersphinx，您需要在 conf.py 中激活它，将字符串 'sphinx.ext.intersphinx' 放入 extensions 列表中，并设置 intersphinx_mapping 配置值。
例如，要链接到 Python 库手册中的 io.open()，您需要像这样设置您的 intersphinx_mapping：
intersphinx_mapping = {'python': ('https://docs.pythonlang.cn/3', None)}
现在，您可以写一个交叉引用，例如 :py:func:`io.open`。任何在当前文档集中没有匹配目标的交叉引用都将在 intersphinx_mapping 中配置的文档集中查找（这需要访问 URL 才能下载有效目标列表）。Intersphinx 也适用于其他一些 域 的角色，包括 :ref:，但它不适用于 :doc:，因为那是一个非域角色。
另请参阅
sphinx.ext.intersphinx 提供了 intersphinx 功能的完整描述。
其他需要涵盖的主题¶
脚注