指令¶
如前所述，指令是显式标记的通用块。Docutils提供了许多指令，而Sphinx提供了更多的指令，并将指令用作主要扩展机制之一。
参见 域 了解域添加的角色。
参见
参考 reStructuredText Primer 获取Docutils提供的指令的概述。
目录¶
由于reStructuredText没有将多个文档互连或将文档拆分为多个输出文件的功能，Sphinx使用自定义指令在组成文档的各文件之间添加关系以及目录。 toctree 指令是核心元素。
备注
可以使用 include 指令简单地将一个文件 包含 到另一个文件中。
备注
要为当前文档（.rst文件）创建目录，请使用标准reStructuredText的 ToC指令。
- .. toctree::¶
在当前位置插入一个"目录树"，使用指令正文中给出的文件的单个目录（包括“子目录树”）。相对文档名（不是以斜杠开头）相对于指令所在的文档，绝对名称相对于源目录。可以提供一个数字的
maxdepth选项来指示树的深度；默认情况下，包括所有级别。[1]"目录树"的渲染结果在每种输出格式中都不同。输出为多个文件的构建器(比如HTML)将其视为超链接的集合。而输出为单个文件的构建器(如LaTeX、man page等)将其替换为目录树上文档的内容。
考虑以下示例(取自Python文档的库引用索引):
.. toctree:: :maxdepth: 2 intro strings datatypes numeric (many more documents listed here)
这可以完成两件事：
插入所有这些文档的目录，最大深度为2，即一层嵌套标题。这些文档中的
toctree指令也计入。Sphinx知道文档
intro、strings等的相对顺序，并且知道它们是所显示文档的子级，即库索引。根据这些信息，它生成"下一章"、"上一章"和"父章"链接。
条目
toctree中的文档标题将自动从引用文档的标题中读取。如果这不是您要的，可以使用类似于reStructuredText超链接(以及Sphinx的 交叉引用语法)的语法来指定显式标题和目标。它看起来像这样:.. toctree:: intro All about strings <strings> datatypes
上面第二行将链接到
strings文档，但会使用"All about strings"做标题，而不是strings文档的标题。您还可以通过提供HTTP URL而不是文档名来添加外部链接。
特殊条目名
self表示包含toctree指令的文档。如果要从目录树生成站点地图，这很有用。最后，源目录（或子目录）中的所有文档都必须出现在某个
toctree指令中；如果Sphinx发现未包含的文件，则会发出警告，因为这意味着无法通过标准导航访问该文件。使用
exclude_patterns显式地从生成中排除文档或目录。使用 the "orphan" metadata 来构建文档，但通知Sphinx不能通过toctree访问它。“根文档”（由
root_doc选择）是目录树层次结构的"根"。它可以用作文档的主页，或者如果不提供:maxdepth:选项，则用作"full table of contents"。在 0.6 版本发生变更: 添加对外部链接和"self"引用的支持。
选项
- :class: class names (a list of class names, separated by spaces)¶
分配 class attributes。这是一个通用选项。例如：
.. toctree:: :class: custom-toc
在 7.4 版本加入.
- :name: label (text)¶
一个隐式目标名称，可以使用
ref引用。这是一个通用选项。例如：.. toctree:: :name: mastertoc foo
在 1.3 版本加入.
- :caption: (text)¶
为toctree添加标题。例如:
.. toctree:: :caption: Table of Contents foo
在 1.3 版本加入.
- :numbered:¶
- :numbered: depth
如果您想在HTML输出中也有章节编号，请将
:numbered:选项添加到 顶级 toctree。例如:.. toctree:: :numbered: foo bar
章节编号从
foo的标题开始。子目录树会自动编号（不要为这些目录树提供numbered标志）。通过将深度作为
numbered的数字参数，也可以对特定深度进行编号。在 0.6 版本加入.
在 1.1 版本发生变更: 添加了数字 depth 参数。
- :titlesonly:¶
仅列出文档标题，而不是同一级别的其他标题。例如:
.. toctree:: :titlesonly: foo bar
在 1.0 版本加入.
- :glob:¶
在目录树条目中解析glob通配符。将所有条目与可用文档列表进行匹配，并按字母顺序将匹配项插入列表中。例如:
.. toctree:: :glob: intro* recipe/* *
这首先包括名称以
intro开头的所有文档，然后是recipe文件夹中的所有文档，然后是所有剩余的文档（当然，除了包含指令的文档） [2]在 0.3 版本加入.
- :reversed:¶
将列表中的条目顺序反转。这在使用
:glob:选项时特别有用。在 1.5 版本加入.
隐藏的toctree仅定义文档层次结构。它不会在指令的位置将链接插入文档中。
如果您有其他导航方式，例如通过手动链接、HTML侧边栏导航，或者如果您在顶级toctree上使用
:includehidden:选项，这就有意义了。在 0.6 版本加入.
如果您想要一个显示完整文档结构的全局目录，可以将
:includehidden:选项添加到 顶级 toctree指令。然后，子页面上的所有其他目录树都可以使用:hidden:选项变得不可见。然后，带有:includehidden:的顶级toctree将包含它们的条目。在 1.2 版本加入.
特殊的名称¶
Sphinx保留了一些文档名供自己使用；您不应该尝试用这些名称创建文档--这会导致问题。
特殊文件名（以及为其生成的页面）为：
genindex这用于通用索引，其中包含来自
index指令和所有生成索引的 object descriptions 的条目。例如，参见Sphinx的 索引。modindex用于Python模块索引，其中每个
py:module指令都有一个条目。例如，参见Sphinx的Python 模块索引。search这用于搜索页面，其中包含一个使用生成的JSON搜索索引和JavaScript的表单，以对生成的文档进行全文搜索；它适用于每个主要浏览器。例如，参见Sphinx的 搜索页面。
以
_开头的每个名称虽然Sphinx目前使用的此类名称很少，但您不应使用此类名称创建文档或包含文档的目录。(将
_用作自定义模板目录的前缀是可以的。)
警告
在文件名中使用不寻常的字符时要小心。某些格式可能会以意想不到的方式解释这些字符：
不要在基于HTML的格式中使用冒号
:。链接到其他部分可能无法工作。ePub格式不使用加号
+。某些资源可能找不到。
段落级标记¶
这些指令创建简短的段落，可以在信息单元内部使用，也可以在普通文本中使用。
Admonitions、messages和warnings¶
Admonition指令创建“admonition”元素，这是一种标准化的信息传递系统，从有用的 tip 到至关重要的 danger。这些指令可以在普通正文元素可以使用的任何地方使用，并且可以包含任意正文元素。有九个特定的命名admonitions和通用的 admonition 指令。
- .. attention::¶
需要读者注意的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
注意
请问我可以引起您的注意吗。
- .. caution::¶
有关读者应谨慎行事的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
小心
请谨慎行事。
- .. danger::¶
如果不注意，可能会导致近在咫尺的危险的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
危险
不要认为可以逃避危险，因为迟早爱情会成为他自己的复仇者。
- .. error::¶
一些指令的故障模式相关信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
错误
ERROR 418：我是一把茶壶。
- .. hint::¶
对读者有帮助的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
提示
看看花盆下面。
- .. important::¶
这是一个至关重要的信息，读者不能忽视。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
重要
这是一个至关重要的声明。
- .. note::¶
读者应该知道的特别重要的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
备注
此功能不适合发送垃圾邮件。
- .. tip::¶
为读者提供一些有用的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
小技巧
记得涂防晒霜！
- .. warning::¶
读者应该非常清楚的重要信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
警告
当心狗。
- .. admonition:: title¶
通用admonition，带有可选标题。指令的内容应以完整的句子编写，并包含所有适当的标点符号。
举例如下：
这是一个标题
这是admonition的内容。
- .. seealso::¶
许多部分包括对模块文档或外部文档的参考列表。这些列表是使用
seealso指令创建的。seealso指令通常放置在任何子部分之前的部分中。seealso指令的内容应为单行或reStructuredText definition list。例如：
.. seealso:: Python's :py:mod:`zipfile` module Documentation of Python's standard :py:mod:`zipfile` module. `GNU tar manual, Basic Tar Format <https://example.org>`_ Documentation for tar archive files, including GNU tar extensions.
参见
- Python的
zipfile模块 Python标准模块
zipfile的文档。- GNU tar manual，基本Tar格式
tar归档文件的文档，包括GNU tar扩展。
- Python的
可折叠文本
在 8.2 版本加入.
每个admonition指令都支持 :collapsible: 选项，以使admonition的内容可折叠（由输出格式支持）。这对于并非始终相关的内容非常有用。默认情况下，可折叠的admonitions最初是打开的，但可以使用 :collapsible: 选项的 open 和 closed 参数来控制，这会更改默认状态。在不支持可折叠内容的输出格式中，文本始终包含在内。例如：
.. note::
:collapsible:
This note is collapsible, and initially open by default.
.. admonition:: Example
:collapsible: open
This example is collapsible, and initially open.
.. hint::
:collapsible: closed
This hint is collapsible, but initially closed.
备注
此注释是可折叠的，并且默认情况下最初是打开的。
示例
这个例子是可折叠的，并且最初是打开的。
提示
这个提示是可折叠的，但最初是关闭的。
描述版本之间的变更¶
- .. version-added:: version [brief explanation]¶
- .. versionadded:: version [brief explanation]¶
此指令记录添加所描述功能的项目版本。当这适用于整个模块或组件时，应将其放置在相关部分的顶部，在任何散文之前。
必须给出第一个参数，并且是有问题的版本；您可以添加第二个参数，其中包含对更改的*简要*解释。
注意
指令头和解释之间不得有空行；这是为了使这些块在标记中在视觉上连续。
在 9.0 版本发生变更:
versionadded指令已重命名为version-added。以前的名称保留为别名。例如：
.. version-added:: 2.5 The *spam* parameter.
在 2.5 版本加入: spam 参数。
- .. version-changed:: version [brief explanation]¶
- .. versionchanged:: version [brief explanation]¶
类似于
version-added，但描述了命名功能以某种方式更改的时间和内容（新参数、更改的副作用等）。在 9.0 版本发生变更:
versionchanged指令已重命名为version-changed。以前的名称保留为别名。例如：
.. version-changed:: 2.8 The *spam* parameter is now of type *boson*.
在 2.8 版本发生变更: spam 参数现在是 boson 类型。
- .. version-deprecated:: version [brief explanation]¶
- .. deprecated:: version [brief explanation]¶
类似于
version-added，但描述了功能何时被弃用。还可以给出简要解释，例如告诉读者使用什么来代替。在 9.0 版本发生变更:
deprecated指令已重命名为version-deprecated。以前的名称保留为别名例如：
.. version-deprecated:: 3.1 Use :py:func:`spam` instead.
自 3.1 版本弃用: 改用
spam()。
- .. version-removed:: version [brief explanation]¶
- .. versionremoved:: version [brief explanation]¶
类似于
version-added，但描述了功能何时被删除。可以提供解释以告诉读者使用什么来代替，或为什么删除该功能。在 7.3 版本加入.
在 9.0 版本发生变更:
versionremoved指令已重命名为version-removed。以前的名称保留为别名。例如：
.. version-removed:: 4.0 The :py:func:`spam` function is more flexible, and should be used instead.
在版本 4.0 移除:
spam()函数更灵活，应该改用它。
展示性的¶
- .. rubric:: title¶
rubric就像一个非正式的标题，不对应于文档的结构，即它不会创建目录节点。
备注
如果rubric的 标题 是“脚注”（或所选语言的等价物），则LaTeX编写器将忽略此评估准则，因为它假定仅包含脚注定义，因此会创建一个空标题。
选项
- :class: class names (a list of class names, separated by spaces)¶
分配 class attributes。这是一个通用选项。
- :heading-level: n (number from 1 to 6)¶
在 7.4.1 版本加入.
使用此选项指定rubric的标题级别。在这种情况下，rubric将呈现为HTML输出的
<h1>到<h6>，或作为LaTeX的相应非编号分节命令（请参见latex_toplevel_sectioning）。
显示代码示例¶
有多种方法可以在Sphinx中显示语法高亮的文字代码块：
使用 reStructuredText literal blocks，可选择与
highlight指令结合使用；用
code-block；
Doctest块只能用于显示交互式Python会话，而其余三个可以用于其他语言。在这三者中，当整个文档或至少其大部分使用具有相同语法的代码块并且应以相同方式进行样式设置时，文字块非常有用。另一方面，当您想要对每个块的样式进行更精细的控制或当您有一个包含使用多种不同语法的代码块的文档时，使用 code-block 指令更有意义。最后，literalinclude 指令对于在文档中包含整个代码文件非常有用。
在所有情况下，语法高亮由 Pygments 提供。使用文字块时，使用源文件中的任何 highlight 指令进行配置。当遇到 highlight 指令时，它将被使用，直到遇到下一个 highlight 指令。若文件中没有 highlight 指令则使用全局高亮语言。默认情况下为 python，但可以使用 highlight_language 进行配置。支持以下值：
无（不突出显示）默认（类似于python3，但有一个回退到none，没有警告高亮显示失败；当highlight_language未设置时的默认值)guess（让Pygments根据内容猜测lexer，只适用于某些可识别的语言）pythonrestc... 以及其他 lexer alias that Pygments supports
如果使用所选语言高亮显示失败（即Pygments发出“错误”标记），则块不会以任何方式高亮显示。
重要
支持的lexer别名列表被绑定到加长版本。如果您想确保一致的高亮显示，您应该修正您的Pygments版本。
- .. highlight:: language¶
例如：
.. highlight:: c
在遇到下一个
highlight指令前，将使用此语言。如前述language可以是Pygments支持的任何lexer别名。选项
- :linenothreshold: threshold (number (optional))¶
允许为代码块生成行号。
此选项接受一个可选数字作为阈值参数。如果给定任何阈值，指令将只为超过N行的代码块生成行号。如果没有给出，将为所有代码块生成行号。
例如：
.. highlight:: python :linenothreshold: 5
- :force: (no value)¶
如果给出，高亮显示的小错误将被忽略。
在 2.1 版本加入.
- .. code-block:: [language]¶
- .. sourcecode:: [language]¶
- .. code:: [language]¶
例如：
.. code-block:: ruby Some Ruby code.
sourcecode指令的别名也可以使用。此指令将语言名称作为参数。它可以是 Pygments 支持的任何lexer别名。如果没有给出，将使用highlight指令的设置。如果未设置，将使用highlight_language。要在其他文本中 内联 显示代码示例，而不是作为单独的块，可以改用code角色。在 2.0 版本发生变更:
语言参数变成可选的。选项
- :linenos: (no value)¶
允许为代码块生成行号:
.. code-block:: ruby :linenos: Some more Ruby code.
- :lineno-start: number (number)¶
设置代码块的第一行号。如果存在，
linenos选项也会自动激活:.. code-block:: ruby :lineno-start: 10 Some more Ruby code, with line numbering starting at 10.
在 1.3 版本加入.
- :emphasize-lines: line numbers (comma separated numbers)¶
强调代码块的特定行:
.. code-block:: python :emphasize-lines: 3,5 def some_function(): interesting = False print('This line is highlighted.') print('This one is not...') print('...but this one is.')
在 1.1 版本加入.
在 1.6.6 版本发生变更: LaTeX支持
emphasize-lines选项。
- :force: (no value)¶
忽略高亮显示的小错误。
在 2.1 版本加入.
- :caption: caption of code block (text)¶
为代码块设置标题。
在 1.3 版本加入.
- :name: a label for hyperlink (text)¶
定义可以通过使用
ref引用的隐式目标名称。例如:.. code-block:: python :caption: this.py :name: this-py print('Explicit is better than implicit.')
为了使用
ref或numref角色交叉引用代码块，必须定义 name 和 caption。然后，name 的参数可以提供给numref以生成交叉引用。例如:See :numref:`this-py` for an example.
使用
ref时，只要定义了 name 并给出了显式标题，就可以生成交叉引用。例如:See :ref:`this code snippet <this-py>` for an example.
在 1.3 版本加入.
- :class: class names (a list of class names separated by spaces)¶
分配 class attributes。这是一个通用选项。
在 1.4 版本加入.
- :dedent: number (number or no value)¶
从代码块中删除缩进字符。当给出数字时，删除前导N个字符。当没有给出参数时，通过
textwrap.dedent()删除前导空格。例如:.. code-block:: ruby :linenos: :dedent: 4 some ruby code
在 1.3 版本加入.
在 3.5 版本发生变更: 支持自动取消缩进。
- .. literalinclude:: filename¶
可以通过将示例文本存储在仅包含纯文本的外部文件中来包含更长的逐字文本显示。可以使用
literalinclude指令包含该文件。[3] 例如，要包含Python源文件example.py，请使用：.. literalinclude:: example.py
文件名通常相对于当前文件的路径。但是，如果它是绝对的（以
/开头），则它是相对于顶级源目录的。通用选项
- :class: class names (a list of class names, separated by spaces)¶
分配 class attributes。这是一个通用选项。
在 1.4 版本加入.
- :caption: caption (text)¶
在包含的内容上方添加标题。如果没有给出参数，则使用文件名作为标题。
在 1.3 版本加入.
格式化选项
- :dedent: number (number or no value)¶
从包含的内容中删除缩进字符。当给出数字时，删除前导N个字符。当没有给出参数时，删除所有常见的前导缩进（使用
textwrap.dedent()）。在 1.3 版本加入.
在 3.5 版本发生变更: 支持自动取消缩进。
- :tab-width: N (number)¶
将制表符展开为N个空格。
在 1.0 版本加入.
- :encoding: (text)¶
明确指定文件的编码。这将覆盖默认编码（UTF-8）。例如：
.. literalinclude:: example.txt :encoding: latin-1
在 0.4.3 版本加入.
- :linenos: (no value)¶
在包含的内容旁边显示行号。默认情况下，行号从1开始计数。可以通过选项
:lineno-start:和:lineno-match:进行更改。
- :lineno-start: number (number)¶
设置要显示的第一行的行号。如果给出，这将自动激活
:linenos:。
- :lineno-match:¶
在仅包含文件的某些部分并显示原始行号时。仅当选择由连续行组成时才允许这样做。
在 1.3 版本加入.
- :emphasize-lines: line numbers (comma separated numbers)¶
强调包含内容的特定行。例如：
.. literalinclude:: example.txt :emphasize-lines: 1,2,4-6
- :language: language (text)¶
选择与当前文件的标准语言（由
highlight或highlight_language设置）不同的高亮语言（Pygments lexer）。
- :force: (no value)¶
忽略高亮显示中的小错误。
在 2.1 版本加入.
选择要包含的内容的选项
- :pyobject: object (text)¶
对于Python文件，仅包含指定的类、函数或方法：
.. literalinclude:: example.py :pyobject: Timer.start
在 0.6 版本加入.
- :lines: line numbers (comma separated numbers)¶
指定要包含的确切行:
.. literalinclude:: example.py :lines: 1,3,5-10,20-
这包括第1行、第3行、第5行到第10行，以及第20行到末尾。
在 0.6 版本加入.
- :start-at: text¶
- :start-after: text¶
- :end-before: text¶
- :end-at: text¶
控制包含文件的哪一部分的另一种方法是使用
start-after和end-before选项（或仅其中之一）。如果start-after作为字符串选项给出，则仅包含跟随包含该字符串的第一行的行。如果end-before作为字符串选项给出，则仅包含在包含该字符串的第一行之前的行。start-at和end-at选项的行为类似，但包含匹配字符串的行。start-after/start-at和end-before/end-at可以具有相同的字符串。start-after/start-at过滤包含选项字符串之前的行（start-at将保留该行）。然后end-before/end-at过滤包含选项字符串之后的行（end-at将保留该行，end-before跳过第一行）。在 0.6 版本加入: 添加
start after和end before选项。在 1.5 版本加入: 添加
start-at和end-at选项。小技巧
要仅选择如下INI文件的
[second-section]，请使用:start-at: [second-section]和:end-before: [third-section]：[first-section] var_in_first=true [second-section] var_in_second=true [third-section] var_in_third=true
当使用标签注释时，这些选项非常有用。使用
:start-after: [initialise]和:end-before: [initialised]保留下面两个注释之间的行：if __name__ == "__main__": # [initialise] app.start(":8000") # [initialised]
当以上述任何方式选择了行时，
emphasize-lines中的行号指的是这些选定的行，从1开始连续计数。
- :prepend: line (text)¶
在包含的代码之前添加一行。例如，当突出显示不包含
<?php或?>标记的PHP代码时，这非常有用。在 1.0 版本加入.
- :append: line (text)¶
在包含的代码之后添加一行。例如，当突出显示不包含
<?php或?>标记的PHP代码时，这非常有用。在 1.0 版本加入.
- :diff: filename¶
显示两个文件的差异。例如：
.. literalinclude:: example.txt :diff: example.txt.orig
这显示了
example.txt和example.txt.orig之间的统一diff格式的差异。在 1.3 版本加入.
在 0.6 版本发生变更: 添加对绝对文件名的支持。
在 1.6 版本发生变更: 当“start after”和“lines”同时使用时，根据“start after”的第一行被认为是“lines”的行号“1”。
术语表¶
- .. glossary::¶
此指令必须包含类似于reStructuredText定义列表的标记，其中包含术语和定义。然后，可以使用
term角色引用这些定义。例如:.. glossary:: environment A structure where information about all documents under the root is saved, and used for cross-referencing. The environment is pickled after the parsing stage, so that successive runs only need to read and parse new and changed documents. source directory The directory which, including its subdirectories, contains all source files for one Sphinx project.
与常规定义列表不同，每个条目允许 多个 术语，术语中允许使用内联标记。你可以链接到所有的术语。例如:
.. glossary:: term 1 term 2 Definition of both terms.
（词汇表排序时，第一个术语决定排序顺序。）
如果要为一般索引项指定"分组键"，可以将"key"作为"term:key"。例如:
.. glossary:: term 1 : A term 2 : B Definition of both terms.
注意，"key"用于按原样分组键。"key"没有被规范化；key "A"和"A"成为不同的组。使用"key"中的整个字符而不是第一个字符；它用于"组合字符序列"和"代理项对"分组键。
在i18n的情况下，即使原始文本只有"term"部分，也可以指定"localized term:key"。在这种情况下，翻译后的"本地化术语"将归入"关键"组。
在 1.1 版本发生变更: 现在支持多个术语和内联标记。
在 1.4 版本发生变更: 术语表术语的索引键应该被认为是 实验性的。
选项
- :sorted:¶
按字母顺序排序条目。
在 0.6 版本加入.
在 4.4 版本发生变更: 在国际化文档中，根据翻译的术语进行排序。
元信息标记¶
- .. sectionauthor:: name <email>¶
标识当前节的作者。参数应包括作者的姓名，以便可以用于演示文稿和电子邮件地址。地址的域名部分应为小写。例子:
.. sectionauthor:: Guido van Rossum <[email protected]>
默认情况下，此标记不会以任何方式反映在输出中（这有助于跟踪贡献），但您可以将配置值
show_authors设置为True以使它们在输出中生成段落。
- .. codeauthor:: name <email>¶
这个
codeauthor可以出现多次、指定代码的作者，就像sectionauthor指定文档片段的作者。它也只在show_authors配置值为True时生成输出。
索引生成标记¶
Sphinx会自动从所有对象描述（如函数、类或属性）中创建索引条目，如 域 中所述。
但是，也可以使用显式标记，使索引更全面，并使索引条目能够在信息单元（如语言引用）中不主要包含在信息单元中的文档中。
- .. index:: <entries>¶
此指令包含一个或多个索引项。每个条目由一个类型和一个值组成，用冒号分隔。
例如：
.. index:: single: execution; context pair: module; __main__ pair: module; sys triple: module; search; path seealso: scope The execution context --------------------- ...
此指令包含五个条目，将被转换为生成的索引中的条目，这些条目链接到索引语句的确切位置（如果是脱机媒体，则是相应的页码）。
由于索引指令在源代码中的位置生成交叉引用目标，所以将它们放在它们引用的对象（比如标题） 之前 是有意义的，如上面的示例所示。
可能的条目类型有：
- single
创建单个索引条目。可通过加入分号来制作子条目（此符号也用于下面描述创建的条目）。例如：
.. index:: single: execution single: execution; context
single: execution创建一个标签为execution的索引条目。single: execution; context给execution条目创建一个子条目context。
- pair
创建两个索引条目的快捷方式。值对必须用分号分隔。例如：
.. index:: pair: loop; statement
创建两个索引条目；
loop; statement和statement; loop。- triple
创建三个索引条目的快捷方式。所有三个值必须用分号分隔。例如：
.. index:: triple: module; search; path
这将创建三个索引条目
module; search path、search; path, module和path; module search。- see
一个创建引用另一个条目的索引条目的快捷方式。例如：
.. index:: see: entry; other
这将创建一个索引条目，从
entry引用到other（即entry：参见other）。- seealso
像
see，但插入'seealso'而不是'see'。- module, keyword, operator, object, exception, statement, builtin
这些 已弃用 的快捷方式都创建两个索引条目。例如，
module: hashlib创建条目module; hashlib和hashlib; module。自 1.0 版本弃用: 这些特定于Python的条目类型已被弃用。
在 7.1 版本发生变更: 删除版本设置为Sphinx 9.0。使用这些条目类型现在将发出带有
index类别的警告。
您可以用感叹号作为前缀来标记“main”索引项。在生成的索引中强调了对“main”条目的引用。例如，如果两页包含：
.. index:: Python
其中一页包含：
.. index:: ! Python
然后在三个反向链接中强调到后一页的反向链接。
对于只包含“单个”项的索引指令，有一种简写的表示法：
.. index:: BNF, grammar, syntax, notation
这将创建四个索引项。
在 1.1 版本发生变更: 添加了
see和seealso类型，并标记了主条目。选项
在 3.0 版本加入.
表格¶
使用 reStructuredText tables，比如
网格表语法（ref），
简单表语法（ref），
csv-table 语法，
或者 list-table 语法。
table 指令用作 grid 和 simple 语法的可选包装器。
它们在HTML输出中工作良好，但将表格渲染为LaTeX很复杂。请检查 latex_table_style 。
在 1.6 版本发生变更: 包含多个段落、块引用、列表、文字块等复杂内容的网格表中的合并单元格（多行、多列、两者）将正确渲染为LaTeX输出。
在 9.0 版本发生变更: LaTeX生成器对在另一个表中嵌套表的部分支持得到了扩展。以前，如果为包含嵌套表的表指定了 longtable 类，Sphinx会引发错误，并且某些情况下不会在Sphinx级别引发错误，但在PDF构建期间会在LaTeX级别失败。这是LaTeX渲染中的一个复杂主题，有时可以通过 tabularcolumns 指令来改进输出。
- .. tabularcolumns:: column spec¶
此指令只影响LaTeX输出，并且仅适用于源文件中的下一个表。强制参数是列规范（在LaTeX习语中称为“对齐前导”）。有关此类列规范的基础知识，请参阅LaTeX文档，例如 wiki page 。
在 0.3 版本加入.
Sphinx使用
tabulary（如果至少有一个单元格包含代码块或嵌套表，则使用tabular）渲染最多30行的表，并使用longtable渲染更多行的表。使用tabulary的优点是它尝试自动计算（在LaTeX内部）合适的列宽。tabulary算法通常效果很好，但在某些情况下，当单元格包含长段落时，该列将被赋予较大的宽度，而其他单元格仅包含单个单词的列可能会变得过窄。tabularcolumns可以通过向LaTeX提供自定义的“alignment preamble”（又名“colspec”）来帮助解决这个问题。备注
当然，完全自动化的解决方案会更好，并且仍然被寄予厚望，但这是
tabulary的一个内在方面，而Sphinx自0.3以来一直在使用它……看起来解决挤压列的问题可能需要对LaTeX包进行重大更改。截至2025年，没有出现好的替代方案。提示
解决所有表格问题的一种方法是向LaTeX序言中注入命令（参见
latex_elements），例如\setlength{\tymin}{1cm}，这会导致所有列至少宽1cm（不包括列间空白）。目前，Sphinx将\tymin配置为至少留出三个字符的空间。这里是一个更复杂的“colspec”，用于4列表格：
.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}
这在Sphinx自己的PDF文档中使用，见 弃用的接口 。关于列宽，这个“colspec”实现了与
:widths:选项设置为40 10 12 38相同的效果，但它注入了额外的效果。备注
如果同时使用了
tabularcolumns和表指令的:widths:选项，:widths:选项将被LaTeX生成器忽略。当然，其他构建器会遵守它。文字块根本无法与
tabulary一起使用，Sphinx将回退到tabularLaTeX环境。只有当它不包含使用tabulary特定的列类型（即L、R、C和J）时，才会在这种情况下使用tabularcolumns规范。除了LaTeX的
l、r、c和p{width}列说明符，以及tabulary特定的L、R、C和J之外，还可以使用（所有表类型）\X{a}{b}，它将列宽配置为总行宽的a/b分数，以及\Y{f}，其中f是小数：例如\Y{0.2}意味着该列将占用行宽的0.2倍。
在 1.6 版本发生变更: Sphinx默认使用 tabulary 中的 J （对齐），而不是 L （左对齐）。要恢复，请在LaTeX序言中包含 \newcolumntype{T}{L}，因为Sphinx实际上使用 T 并将其默认设置为 J 的别名。
在 9.0 版本发生变更: 以前，如果表格中至少有一个单元格包含列表、对象描述、块引用（等等...）等“有问题”的元素，因为这些内容与 tabulary 不兼容，所以Sphinx不会使用 tabulary 。在 9.0 中，一种已经用于合并单元格的技术被扩展到这种情况，唯一的“有问题”的内容是代码块和嵌套表。因此，包含（仅）具有多个段落、项目符号或枚举列表或行块的单元格的表格现在将更好地适应其内容（如果不是由 longtable 渲染）。具有对象描述或警告的单元格仍然倾向于使表格填满整个文本区域宽度，但该表格中没有此类内容的列将更紧凑。
提示
要强制使用LaTeX longtable 环境，请将 longtable 作为 :class: 选项传递给 table、csv-table 或 list-table。其他表格请使用 rst-class 。
数学¶
数学的输入语言是LaTeX标记。这是纯文本数学表示法的事实标准，而且还有一个优点，即在构建LaTeX输出时不需要进一步的翻译。
请记住，当您将数学标记放在被 autodoc 读取的 Python docstrings 中时要么必须将所有反斜杠加倍，要么使用Python原始字符串（r"raw"）。
- .. math::¶
指示显示的数学（取整行为自己的数学）。
指令支持多个方程式，这些方程式应该用空行分隔：
.. math:: (a + b)^2 = a^2 + 2ab + b^2 (a - b)^2 = a^2 - 2ab + b^2
此外，每个等式都是在一个“split”环境中设置的，这意味着您可以在一个等式中有多条对齐的直线，以“&”对齐，并用“\”分隔：
.. math:: (a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2
有关详细信息，请参阅 AmSMath LaTeX package 的文档。
当数学只有一行文本时，它也可以作为一个指令参数：
.. math:: (a + b)^2 = a^2 + 2ab + b^2
选项
- :class: class names (a list of class names, separated by spaces)¶
分配 class attributes。这是一个通用选项。
- :label: label (text)¶
通常情况下，方程式不编号。如果你想让你的方程式得到一个数字，使用
标签选项。当给定时，它将为表达式选择一个内部标签，通过该标签可以交叉引用，并生成一个表达式编号。参见eq为例。编号样式取决于输出格式。
- :no-wrap:¶
防止在数学环境中换行给定的数学。当您提供此选项时，您必须自己确保数学正确设置。例如：
.. math:: :no-wrap: \begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}
在 8.2 版本发生变更: 指令选项
:nowrap:已重命名为:no-wrap:。以前的名称已作为别名保留，但将在Sphinx的未来版本中弃用和删除。
参见
- Sphinx中HTML输出的数学支持
用HTML生成器呈现数学选项。
latex_engine说明如何配置LaTeX builder以在数学标记中支持Unicode文本。
语法生成显示¶
提供了特殊的标记来显示形式语法的生成。该标记很简单，并不试图模拟 BNF （或任何派生形式）的所有方面，但提供了足够的内容来允许以符号的使用方式显示上下文无关的语法，以便将符号的使用呈现为指向该符号定义的超链接。有以下指令：
- .. productionlist:: [production_group]¶
此指令用于封闭一组生成。每个生成都在单独的一行上给出，并由冒号分隔名称和后续定义。如果定义跨越多行，则每个续行必须以与第一行相同的列处放置的冒号开头。在
productionlist指令参数中不允许有空行。可选的 production_group 指令参数用于区分属于不同语法的不同生成列表集。因此，具有相同 production_group 的多个生成列表在同一范围内定义规则。这也可用于将长或复杂语法的描述拆分为多个具有相同 production_group 的
productionlist指令。定义可以包含标记为解释文本的标记名称（例如"
sum ::= `integer` "+" `integer`"），以生成对这些标记生成的交叉引用。此类交叉引用隐式引用来自当前组的生成。要引用来自另一个语法的生成，标记名称必须以组名称和冒号为前缀，例如“other-group:sum”。如果不应在生成中显示标记的组，则可以在其前面加上波浪号，例如“~other-group:sum”。要引用来自未命名语法的生成，标记应以冒号为前缀，例如“:sum”。在生成中不进行进一步的reStructuredText解析，因此不需要转义特殊字符（*、|等）。可以使用
token角色在生成列表之外交叉引用标记生成。如果您使用了 production_group 参数，则标记名称必须以组名称和冒号为前缀，例如“my_group:sum”而不是仅“sum”。可以使用标准的 cross-referencing modifiers 与:token:角色，例如自定义链接文本和使用波浪号（~）抑制组名称。
以下是摘自《Python参考手册》的示例：
.. productionlist::
try_stmt: try1_stmt | try2_stmt
try1_stmt: "try" ":" `suite`
: ("except" [`expression` ["," `target`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`
脚注