入门

一旦Sphinx完成 安装，您就可以继续设置您的第一个Sphinx项目了。 为了简化入门过程，Sphinx提供了一个工具 sphinx-quickstart，它将生成一个文档源目录并用一些默认值填充它。 我们将在这里使用 sphinx-quickstart 工具，尽管它没有必要使用。

设置文档源

Sphinx集合 reStructuredText 文档源的根目录称为 source directory。该目录还包含Sphinx配置文件 conf.py，您可以在其中配置Sphinx如何读取源代码和构建文档的所有方面。 [1]

Sphinx附带一个名为 sphinx-quickstart 的脚本，它设置一个源目录并创建一个默认的 conf.py ，其中包含几个问题中最有用的配置值。要使用它，请运行:

$ sphinx-quickstart

回答每个问题。一定要对 autodoc 扩展名回答”yes”，因为我们稍后会使用它。

还有一个自动的”API documentation”生成器，名为 sphinx-apidoc ;请参阅 sphinx-apidoc 了解详情。

定义文档结构

让我们假设你运行 sphinx-quickstart。它创建了一个源目录 conf.py 和一个主文件 index.rst (如果你接受了默认值)。 master document 的主要功能是作为欢迎页面，并包含”目录树”(或*toctree*)的根。这是Sphinx为reStructuredText添加的主要功能之一，reStructuredText是一种将多个文件连接到单个文档层次结构的方法。

reStructuredText 指令

toctree is a reStructuredText directive, a very versatile piece of markup. Directives can have arguments, options and content.

参数 在指令名后面的双冒号后直接给出。每个指令决定它是否可以有参数，以及有多少参数。

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

Content 在空行后面跟着选项或参数。Content 在空行后跟一个选项或参数。

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

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

.. toctree::
   :maxdepth: 2

您可以在指令的 content 中添加列出它们的文档:

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

这正是本文档的 toctree 的外观。要包含的文件如下 document names，简而言之就是你不使用文件扩展名并使用正斜杠(/)作为目录分隔符。

阅读更多关于 toctree指令 。

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

添加内容

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

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

待处理

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

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

运行构建

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

$ sphinx-build -b html sourcedir builddir

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

对于以下所有选项，请参阅 sphinx-build手册页 sphinx-build 支持。

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

$ make html

这些可以通过运行 make 来执行，它包含构建器的名称。例如。

如何生成PDF文档？

make latexpdf 运行 LaTeX 生成器 并随时为你调用pdfTeX工具链。

待处理

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

记录对象

Sphinx的主要目标之一是简单地记录 objects (在很一般意义上)在任何 domain 。 域是属于一起的对象类型的集合，带有标记以创建和引用这些对象的描述。

最突出的域是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 的项。 (等等。)

该指令的参数是你描述的对象的 signature ，内容是它的文档。可以给出多个签名，每个签名都在其自己的行中。

Python域也恰好是默认域，因此您不需要在标记前加上域名。

.. function:: enumerate(sequence[, start=0])

   ...

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

还有几个用于记录其他类型的Python对象的指令，例如 py:class 或 py:method 。对于每种对象类型，还有一个交叉引用 role 。这个标记将创建一个指向 enumerate() 文档的链接。

The :py:func:`enumerate` function can be used for ...

这是 proof: 链接到 enumerate() 。

同样，如果Python域是默认域，则可以省略 py: 。哪个文件包含 enumerate() 的实际文档并不重要; Sphinx会找到它并创建一个链接。

每个域都有特殊的规则来表示签名的外观，并使格式化的输出看起来很漂亮，或添加特定的功能，如链接到参数类型，例如在C/C ++域中。

请参阅 域，了解所有可用域及其指令/角色。

基本配置

之前我们提到过 conf.py 文件控制着Sphinx处理文档的方式。在该文件中，它作为Python源文件执行，您可以分配配置值。对于高级用户: 由于它是由Sphinx执行的，因此您可以在其中执行非平凡的任务，例如扩展 sys.path 或导入模块以找出您正在记录的版本。

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

请记住，该文件使用Python语法来表示字符串，数字，列表等。默认情况下，文件以UTF-8保存，如第一行中的编码声明所示。如果在任何字符串值中使用非ASCII字符，则需要使用Python Unicode字符串(如 project =u'Exposé' )。

有关所有可用配置值的文档，请参阅 配置 。

待处理

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

Autodoc

在记录Python代码时，通常会在文档字符串中的源文件中放入大量文档。 Sphinx支持在模块中包含docstrings extension (扩展名是为Sphinx项目提供附加功能的Python模块)，称为 autodoc 。

为了使用 autodoc ，你需要在 conf.py 中激活它，方法是将字符串 'sphinx.ext.autodoc' 放入分配给 extensions 配置的列表中值。 然后，您可以使用其他一些指令。

例如，要记录函数 io.open() ，从源文件中读取它的签名和docstring，你就写下:

.. autofunction:: io.open

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

.. automodule:: io
   :members:

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

警告

autodoc 导入 要记录的模块。如果任何模块对导入有副作用，那么当运行 sphinx-build 时，这些将由 autodoc 执行。

如果您记录脚本(而不是库模块)，请确保它们的主例程受 if __name__ =='__ main __' 条件的保护。

有关autodoc功能的完整描述，请参阅 sphinx.ext.autodoc 。

待处理

将此文档移至另一部分

Intersphinx

包括 Python documentation 在内的许多Sphinx文档都在Internet上发布。如果要从文档中链接到此类文档，可以使用 sphinx.ext.intersphinx 。

为了使用intersphinx，你需要在 conf.py 中激活它，方法是将字符串 'sphinx.ext.intersphinx' 放入 extensions 列表并设置 intersphinx_mapping 配置值。

例如，要链接到Python库手册中的 io.open() ，你需要设置 intersphinx_mapping 如下

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

现在，您可以编写一个交叉引用，如 :py:func:`io.open` 。任何在当前文档集中没有匹配目标的交叉引用都将在配置的文档集中查找 intersphinx_mapping (这需要访问URL才能下载有效目标列表)。 Intersphinx也适用于其他一些 domain 的角色，包括 :ref: ，但它不适用于 :doc: ，因为那是非域角色。

有关intersphinx功能的完整描述，请参阅 sphinx.ext.intersphinx 。

更多主题

• 其他扩展 :
• 静态文件
• 选择主题
• Setuptools集成
• 模板
• 使用扩展
• 写扩展

脚注

[1]	这是通常的布局。但是， file:conf.py 也可以存在于另一个目录中 configuration directory 。 有关更多信息，请参阅 sphinx-build手册页 。