开始使用¶
Sphinx 是一个文档生成器，或者说是一个工具，它可以将一组纯文本源文件翻译成各种输出格式，自动生成交叉引用、索引等。也就是说，如果你有一个目录，其中包含一堆 reStructuredText 或 Markdown 文档，Sphinx 可以生成一系列 HTML 文件、PDF 文件（通过 LaTeX）、man pages 以及更多。
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 中列出的文件并添加内容，它们的节标题将被插入到 toctree 指令放置的位置（最多 maxdepth 级别）。此外，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 man page 以了解 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])¶
返回一个迭代器，该迭代器产生索引的元组和 sequence 的项目。（等等。）
指令的参数是你描述的对象的签名，内容是它的文档。可以给出多个签名，每个签名占一行。
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，你需要通过将字符串 'sphinx.ext.intersphinx' 放入 extensions 列表并设置 intersphinx_mapping 配置值，在 conf.py 中激活它。
例如，要链接到 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 功能的完整描述。
更多主题待涵盖¶
脚注