入门¶
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-autobuild运行以下命令
$ sphinx-autobuild source-dir output-dir
然而，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的扩展（扩展是一个为 Sphinx 项目提供额外功能的 Python 模块）来包含模块中的文档字符串。
另请参阅
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 功能的完整描述。
更多待讨论的主题¶
脚注