指令

如前所述，指令是一种通用的显式标记块。虽然 Docutils 提供了一些指令，但 Sphinx 提供了更多指令，并将指令用作主要的扩展机制之一。

有关域添加的角色，请参阅 域。

另请参阅

请参阅 reStructuredText 入门，以概述 Docutils 提供的指令。

目录

由于 reStructuredText 没有互连多个文档或将文档拆分为多个输出文件的工具，因此 Sphinx 使用自定义指令在文档组成的单个文件之间添加关系，以及目录。 toctree 指令是核心元素。

注意

可以使用 include 指令在另一个文件中简单地“包含”一个文件。

注意

要为当前文档（.rst 文件）创建目录，请使用标准 reStructuredText contents 指令。

.. toctree::

此指令在当前位置插入一个“TOC 树”，使用指令主体中给定的文档的各个 TOC（包括“子 TOC 树”)。相对文档名称（不以斜杠开头）相对于包含指令的文档，绝对名称相对于源目录。可以提供一个数字 maxdepth 选项来指示树的深度；默认情况下，包含所有级别。[1]

“TOC 树”的表示形式在每种输出格式中都发生了变化。输出多个文件的构建器（例如 HTML）将其视为超链接的集合。另一方面，输出单个文件的构建器（例如 LaTeX、手册页等）将其替换为 TOC 树上文档的内容。

考虑以下示例（摘自 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 文档，但将使用标题“关于字符串的一切”而不是 strings 文档的标题。

您还可以通过提供 HTTP URL 而不是文档名称来添加外部链接。

特殊条目名称 self 代表包含 toctree 指令的文档。如果您想从 toctree 生成“站点地图”，这将非常有用。

最后，源目录（或子目录）中的所有文档都必须出现在某个 toctree 指令中；如果 Sphinx 发现未包含的文件，它将发出警告，因为这意味着无法通过标准导航访问该文件。

使用 exclude_patterns 显式排除文档或目录，以完全停止构建。使用 “孤儿”元数据 来构建文档，但通知 Sphinx 无法通过 toctree 访问它。

“根文档”（由 root_doc 选择）是 TOC 树层次结构的“根”。它可以作为文档的主页，或者如果您不提供 :maxdepth: 选项，则可以作为“完整目录”。

版本 0.6 中的更改： 添加了对外部链接和“self”引用的支持。

选项

:class: class names (用 空格 分隔 的 类 名称 列表)

分配 类属性。这是一个 常用选项。例如

.. toctree::
   :class: custom-toc

在版本 7.4 中添加。

:name: label (文本)

可以使用 ref 引用的隐式目标名称。这是一个 常用选项。例如

.. toctree::
   :name: mastertoc

   foo

在版本 1.3 中添加。

:caption: (文本)

为 toctree 添加标题。例如

.. toctree::
   :caption: Table of Contents

    foo

在版本 1.3 中添加。

:numbered:
:numbered: depth

如果您希望即使在 HTML 输出中也显示章节编号，请将 :numbered: 选项添加到顶级 toctree 中。例如

.. toctree::
   :numbered:

   foo
   bar

然后从 foo 的标题开始编号。子 toctree 会自动编号（不要为它们提供 numbered 标志）。

还可以通过向 numbered 提供数字参数来指定特定深度的编号。

在版本 0.6 中添加。

版本 1.1 中的更改： 添加了数字 depth 参数。

:titlesonly:

仅列出文档标题，而不是同一级别的其他标题。例如

.. toctree::
   :titlesonly:

   foo
   bar

在版本 1.0 中添加。

:glob:

在 toctree 条目中解析 glob 通配符。所有条目都与可用文档列表匹配，匹配项按字母顺序插入列表中。例如

.. toctree::
   :glob:

   intro*
   recipe/*
   *

这包括首先所有名称以intro开头的文档，然后是recipe文件夹中的所有文档，最后是所有剩余的文档（当然，除了包含该指令的那个文档）。[2]

在版本 0.3 中添加。

:reversed:

反转列表中条目的顺序。当使用:glob:选项时，这尤其有用。

在版本 1.5 中添加。

:hidden:

隐藏的 toctree 仅定义文档层次结构。它不会在指令所在位置插入文档中的链接。

如果您有其他导航方式，例如通过手动链接、HTML 侧边栏导航，或者如果您在顶级 toctree 上使用:includehidden:选项，则这很有意义。

在版本 0.6 中添加。

:includehidden:

如果您希望一个全局目录显示完整的文档结构，您可以将:includehidden:选项添加到顶级 toctree 指令中。然后，子页面上的所有其他 toctree 可以使用:hidden:选项设置为不可见。带有:includehidden:的顶级 toctree 然后将包含它们的条目。

在版本 1.2 中添加。

特殊名称

Sphinx 保留了一些文档名称供自身使用；您不应该尝试创建具有这些名称的文档 - 这会导致问题。

特殊文档名称（以及为其生成的页面）为

  • genindex

    这用于通用索引，该索引由index指令和所有生成索引的对象描述填充。例如，请参阅 Sphinx 的索引。

  • modindex

    这用于 Python 模块索引，其中包含每个py:module指令的一个条目。例如，请参阅 Sphinx 的Python 模块索引。

  • search

    这用于搜索页面，其中包含一个表单，该表单使用生成的 JSON 搜索索引和 JavaScript 对生成的文档进行全文搜索以查找搜索词；它适用于每个主要浏览器。例如，请参阅 Sphinx 的搜索页面。

  • 所有以_开头的名称

    虽然 Sphinx 目前很少使用此类名称，但您不应该创建具有此类名称的文档或包含文档的目录。（使用_作为自定义模板目录的前缀是可以的。）

警告

注意文件名中不常见的字符。某些格式可能会以意想不到的方式解释这些字符。

  • 不要对基于 HTML 的格式使用冒号:。指向其他部分的链接可能无法正常工作。

  • 不要对 ePub 格式使用加号+。某些资源可能找不到。

段落级标记

这些指令创建简短的段落，并且可以在信息单元以及普通文本中使用。

警告、消息和提示

警告指令创建“警告”元素，这是一种标准化的信息传递系统，从有帮助的tip到至关重要的danger。这些指令可以在任何普通正文元素可以使用的地方使用，并且可以包含任意正文元素。有九个特定的命名警告和通用的admonition指令。

.. attention::

需要读者注意的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

注意

请您注意一下。

.. caution::

关于读者应谨慎行事的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

注意

请谨慎行事。

.. danger::

如果未注意，可能会导致即将发生的危险的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

危险

不要以为可以逃避危险，因为迟早爱都会成为自己复仇者。

.. error::

与某种故障模式相关的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

错误

错误 418：我是一个茶壶。

.. hint::

对读者有帮助的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

提示

看看花盆下面。

.. important::

至关重要的信息，读者绝不能忽视。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

重要

这是一个至关重要的声明。

.. note::

读者应该知道的一条特别重要的信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

注意

此函数不适用于发送垃圾邮件。

.. tip::

一些对读者有用的信息片段。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

提示

记得涂防晒霜！

.. warning::

读者应该非常注意的一条重要信息。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

警告

当心狗。

.. admonition:: title

一个通用的警告，带有一个可选的标题。指令的内容应以完整的句子编写，并包含所有适当的标点符号。

示例

这是一个标题

这是警告的内容。

.. seealso::

许多部分包含指向模块文档或外部文档的参考列表。这些列表是使用seealso指令创建的。

seealso指令通常放置在任何子部分之前的某个部分中。seealso指令的内容应为单行或 reStructuredText 定义列表。

示例

.. 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.

另请参阅

模块 zipfile

zipfile标准模块的文档。

GNU tar 手册，基本 Tar 格式

tar 归档文件的文档，包括 GNU tar 扩展。

描述版本之间的更改

.. versionadded:: version [brief explanation]

此指令记录添加所描述功能的项目的版本。当这适用于整个模块或组件时，应将其放在相关部分的顶部，在任何散文之前。

必须给出第一个参数，它是相关版本；您可以添加第二个参数，该参数包含对更改的简要说明。

注意

指令标题和说明之间不能有空行；这样做是为了使这些块在标记中视觉上连续。

示例

.. versionadded:: 2.5
   The *spam* parameter.

在版本 2.5 中添加： spam 参数。

.. versionchanged:: version [brief explanation]

类似于versionadded，但描述了何时以及命名功能以何种方式发生了更改（新参数、更改的副作用等）。

示例

.. versionchanged:: 2.8
   The *spam* parameter is now of type *boson*.

在版本 2.8 中更改： spam 参数现在是 boson 类型。

.. deprecated:: version [brief explanation]

类似于 versionadded，但描述了该功能何时被弃用。还可以提供一个简短的解释，例如告诉读者应该使用什么替代方案。

示例

.. deprecated:: 3.1
   Use :py:func:`spam` instead.

自版本 3.1 起已弃用： 请改用 spam()。

.. versionremoved:: version [brief explanation]

类似于 versionadded，但描述了该功能何时被移除。可以提供解释来告诉读者应该使用什么替代方案，或者为什么移除该功能。

在版本 7.3 中添加。

示例

.. versionremoved:: 4.0
   The :py:func:`spam` function is more flexible, and should be used instead.

在版本 4.0 中移除： spam() 函数更加灵活，应该改用它。

表现形式

.. rubric:: title

Rubric 类似于非正式标题，它不对应于文档的结构，即它不会创建目录节点。

注意

如果 rubric 的标题是“脚注”（或所选语言的等效项），则 LaTeX 编写器会忽略此 rubric，因为它假定它仅包含脚注定义，因此会创建空标题。

选项

:class: class names (a list of class names, separated by spaces)

分配 类属性。这是一个 常用选项。

:name: label (text)

一个隐式目标名称，可以使用 ref 进行引用。这是一个 常用选项。

:heading-level: n (number from 1 to 6)

在版本 7.4.1 中添加。

使用此选项指定 rubric 的标题级别。在这种情况下，rubric 将被渲染为 <h1> 到 <h6>（用于 HTML 输出），或作为 LaTeX 的相应非编号分节命令（请参阅 latex_toplevel_sectioning）。

.. centered::

此指令创建一行居中加粗的文本。

自版本 1.1 起已弃用： 此仅用于演示的指令是旧版本的遗留产物。请改用 rst-class 指令并添加适当的样式。

.. hlist::

此指令必须包含一个项目符号列表。它会将其转换为更紧凑的列表，方法是根据构建器水平分布多个项目，或减少项目之间的间距。

选项

:columns: n (int)

列数；默认为 2。例如

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

在版本 0.6 中添加。

显示代码示例

有多种方法可以在 Sphinx 中显示语法高亮的文字代码块

Doctest 块只能用于显示交互式 Python 会话，而其余三个可以用于其他语言。在这三个中，文字块在整个文档或至少其大部分内容使用具有相同语法的代码块并且应以相同方式设置样式时很有用。另一方面，code-block 指令在您希望更精细地控制每个块的样式或文档包含使用多种不同语法的代码块时更有意义。最后，literalinclude 指令可用于在文档中包含整个代码文件。

在所有情况下，语法高亮都由 Pygments 提供。使用文字块时，这可以通过源文件中的任何 highlight 指令进行配置。遇到 highlight 指令时，它将一直使用到遇到下一个 highlight 指令为止。如果文件中没有 highlight 指令，则使用全局高亮语言。默认为 python，但可以使用 highlight_language 配置值进行配置。支持以下值

  • none（无高亮）

  • default（类似于 python3，但回退到 none，并且不会在高亮失败时发出警告；当未设置 highlight_language 时使用的默认值）

  • guess（让 Pygments 根据内容猜测词法分析器，仅适用于某些易于识别的语言）

  • python

  • rest

  • c

  • …以及 Pygments 支持的任何其他 词法分析器别名

如果使用所选语言进行高亮失败（即 Pygments 发出“错误”标记），则该块将不会以任何方式进行高亮。

重要

支持的词法分析器别名列表与 Pygment 版本相关联。如果您想确保一致的高亮，则应修复 Pygments 的版本。

.. highlight:: language

示例

.. highlight:: c

此语言将一直使用到遇到下一个 highlight 指令为止。如前所述，language 可以是 Pygments 支持的任何词法分析器别名。

选项

: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 支持的任何词法分析器别名。如果未给出，则将使用 highlight 指令的设置。如果未设置，则将使用 highlight_language。要内联显示其他文本中的代码示例，而不是作为单独的块，可以使用 code 角色。

在版本 2.0 中更改： language 参数变为可选。

选项

: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 选项。

: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)

图形的类名。

版本 1.4 中新增。

:dedent: number (number or no value)

从代码块中去除缩进字符。如果给定数字，则移除前 N 个字符。如果未给出参数，则通过 textwrap.dedent() 移除前导空格。例如

.. code-block:: ruby
   :linenos:
   :dedent: 4

       some ruby code

在版本 1.3 中添加。

版本 3.5 中更改: 支持自动去除缩进。

:force: (no value)

如果给出，则忽略高亮显示中的小错误。

在版本 2.1 中添加。

.. literalinclude:: filename

可以通过将示例文本存储在仅包含纯文本的外部文件中来包含更长的逐字文本显示。可以使用 literalinclude 指令包含该文件。[3] 例如，要包含 Python 源文件 example.py，请使用

.. literalinclude:: example.py

文件名通常相对于当前文件的路径。但是，如果它是绝对路径（以 / 开头），则它相对于顶级源目录。

其他选项

与 code-block 一样，该指令支持 linenos 标志选项以打开行号，lineno-start 选项以选择第一行行号，emphasize-lines 选项以强调特定行，name 选项以提供隐式目标名称，dedent 选项以去除代码块的缩进字符，以及 language 选项以选择与当前文件标准语言不同的语言。此外，它还支持 caption 选项；但是，这可以不带参数提供以使用文件名作为标题。带选项的示例

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

如果提供带有所需制表符宽度的 tab-width 选项，则输入中的制表符将被展开。

包含的文件假定为使用 source_encoding 编码。如果文件具有不同的编码，则可以使用 encoding 选项指定。

.. literalinclude:: example.py
   :encoding: latin-1

该指令还支持仅包含文件的一部分。如果它是一个 Python 模块，则可以使用 pyobject 选项选择要包含的类、函数或方法。

.. literalinclude:: example.py
   :pyobject: Timer.start

这将仅包含属于文件中 Timer 类中 start() 方法的代码行。

或者，可以通过提供 lines 选项来指定要包含的确切行。

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

这包括第 1、3、5 到 10 行以及第 20 行到最后一行。

控制包含文件哪一部分的另一种方法是使用 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 跳过第一行）的行。

注意

如果要像下面这样仅选择 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: [initialize] 和 :end-before: [initialized] 选项保留注释之间的行。

if __name__ == "__main__":
    # [initialize]
    app.start(":8000")
    # [initialized]

当以任何上述方式选择行时，emphasize-lines 中的行号将引用这些选定的行，从 1 开始连续计数。

在指定要显示的文件的特定部分时，显示原始行号可能很有用。这可以通过使用 lineno-match 选项来完成，但是仅当选择包含连续行时才允许使用该选项。

可以使用 prepend 和 append 选项分别在包含的代码之前和/或之后添加一行。这在例如突出显示不包含 <?php/?> 标记的 PHP 代码时很有用。

如果要显示代码的差异，可以通过提供 diff 选项来指定旧文件。

.. literalinclude:: example.py
   :diff: example.py.orig

这显示了 example.py 和 example.py.orig 之间的差异，并使用统一差异格式。

一个 force 选项可以忽略突出显示上的小错误。

版本 0.4.3 中更改: 添加了 encoding 选项。

版本 0.6 中更改: 添加了 pyobject、lines、start-after 和 end-before 选项，以及对绝对文件名的支持。

版本 1.0 中更改: 添加了 prepend、append 和 tab-width 选项。

版本 1.3 中更改: 添加了 diff、lineno-match、caption、name 和 dedent 选项。

版本 1.4 中更改: 添加了 class 选项。

版本 1.5 中更改: 添加了 start-at 和 end-at 选项。

版本 1.6 中更改： 同时使用 start-after 和 lines 时，根据 start-after 的第一行将被视为 lines 的第 1 行。

版本 2.1 中更改： 添加了 force 选项。

版本 3.5 中更改: 支持自动去除缩进。

术语表

.. 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.

（对术语表进行排序时，第一个术语决定排序顺序。）

如果要为通用索引条目指定“分组键”，可以将“键”作为“term : key”。例如

.. glossary::

   term 1 : A
   term 2 : B
      Definition of both terms.

请注意，“键”按原样用于分组键。“键”不会被规范化；键“A”和“a”将成为不同的组。“键”中的所有字符都将被使用，而不是第一个字符；它用于“组合字符序列”和“代理对”的分组键。

在 i18n 场景中，即使原始文本仅包含“term”部分，您也可以指定“localized term : key”。在这种情况下，翻译后的“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 类似，但插入“另请参见”而不是“参见”。

module、keyword、operator、object、exception、statement、builtin

这些已弃用的快捷方式都创建两个索引条目。例如，module: hashlib 创建条目 module; hashlib 和 hashlib; module。

自版本 1.0 起弃用： 这些 Python 特定条目类型已弃用。

版本 7.1 中更改： 移除版本设置为 Sphinx 9.0。使用这些条目类型现在将使用 index 类别发出警告。

您可以通过在“主要”索引条目前面加上感叹号来标记它们。生成的索引中对“主要”条目的引用将被强调。例如，如果两页包含

.. index:: Python

并且一页包含

.. index:: ! Python

则这三个反向链接中，指向后一页的反向链接将被强调。

对于仅包含“single”条目的索引指令，可以使用简写表示法

.. index:: BNF, grammar, syntax, notation

这将创建四个索引条目。

版本 1.1 中更改： 添加了 see 和 seealso 类型，以及主要条目的标记。

选项

:name: 超链接的标签 (文本)

定义隐式目标名称，可以使用 ref 进行引用。例如

.. index:: Python
   :name: py-index

版本 3.0 中添加。

:index:

虽然 index 指令是块级标记，并链接到下一段的开头，但还有一个相应的角色可以直接设置链接目标在其使用的位置。

角色的内容可以是一个简单的短语，然后将其保留在文本中并用作索引条目。它也可以是文本和索引条目的组合，样式类似于交叉引用的显式目标。在这种情况下，“目标”部分可以是指令上面描述的完整条目。例如

This is a normal reStructuredText :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.

版本 1.1 中新增。

基于标签包含内容

.. only:: <expression>

仅当表达式为真时才包含指令的内容。表达式应由标签组成，如下所示

.. only:: html and draft

未定义的标签为假，已定义的标签为真（标签可以通过 --tag 命令行选项或在 conf.py 中定义，请参见 此处）。支持布尔表达式（如 (latex or html) and draft），并且可以使用括号。

当前构建器的格式和名称（html、latex 或 text）始终设置为标签 [4]。为了明确区分格式和名称，它们也以前缀 format_ 和 builder_ 添加，例如，epub 构建器定义了标签 html、epub、format_html 和 builder_epub。

这些标准标签是在读取配置文件之后设置的，因此在配置文件中不可用。

所有标签都必须遵循标准的 Python 标识符语法，如标识符和关键字文档中所述。也就是说，标签表达式只能包含符合 Python 变量语法的标签。在 ASCII 中，这包括大写和小写字母 A 到 Z、下划线 _ 以及（除了第一个字符外）数字 0 到 9。

在版本 0.6 中添加。

1.2 版中的更改: 添加了构建器的名称和前缀。

警告

此指令旨在仅控制文档内容。它不能控制章节、标签等。

表格

使用 reStructuredText 表格，即：

该 table 指令用作网格和简单语法的可选包装器。

它们在 HTML 输出中工作良好，但将表格渲染到 LaTeX 比较复杂。请查看 latex_table_style。

1.6 版中的更改: 包含复杂内容（如多个段落、块引用、列表、文字块）的网格表格中的合并单元格（多行、多列、两者兼有）将正确渲染到 LaTeX 输出中。

.. tabularcolumns:: column spec

此指令仅影响源代码中下一个表格的 LaTeX 输出。必填参数是列规范（在 LaTeX 惯例中称为“对齐序言”）。请参阅 LaTeX 文档，例如 wiki 页面，了解此类列规范的基础知识。

在版本 0.3 中添加。

注意

tabularcolumns 与表格指令的 :widths: 选项冲突。如果同时指定了这两个选项，则 :widths: 选项将被忽略。

Sphinx 将使用 longtable 渲染超过 30 行的表格。除了 l、r、c 和 p{width} 列说明符之外，还可以使用 \X{a}{b}（1.5 版中的新增功能），它将列宽配置为总行宽的 a/b 分数，以及 \Y{f}（1.6 版中的新增功能），其中 f 是十进制数：例如 \Y{0.2} 表示该列将占用 0.2 倍的行宽。

当此指令用于最多 30 行的表格时，Sphinx 将使用 tabulary 渲染它。然后，您可以使用特定的列类型 L（左对齐）、R（右对齐）、C（居中）和 J（两端对齐）。它们具有 p{width} 的效果（即每个单元格都是一个具有指定内部文本对齐方式和自动计算的 width 的 LaTeX \parbox）。

警告

  • 包含列表式元素（如对象描述、块引用或任何类型的列表）的单元格与 LRCJ 列类型不兼容。然后，列类型必须是某个具有显式 width 的 p{width}（或 \X{a}{b} 或 \Y{f}）。

  • 文字块根本不适用于 tabulary。Sphinx 将回退到 tabular 或 longtable 环境并生成合适的列规范。

在没有 tabularcolumns 指令的情况下，并且对于最多 30 行且没有上述警告中所述的有问题的单元格的表格，Sphinx 将使用 tabulary 并对每一列使用 J 列类型。

1.6 版中的更改: 以前，使用 L 列类型（文本左对齐）。要恢复此设置，请在 LaTeX 序言中包含 \newcolumntype{T}{L}，因为实际上 Sphinx 使用 T 并将其默认设置为 J 的别名。

提示

使用 tabulary 时的一个常见问题是，内容较少的列似乎会被“压缩”。例如，您可以将 \setlength{\tymin}{40pt} 添加到 LaTeX 序言中，以确保最小列宽为 40pt，tabulary 的默认值 10pt 太小了。

提示

要强制使用 LaTeX longtable 环境，请将 longtable 作为 :class: 选项传递给 table、csv-table 或 list-table。对于其他表格，请使用 rst-class。

数学

数学的输入语言是 LaTeX 标记。这是纯文本数学符号的事实标准，并且具有在构建 LaTeX 输出时无需进一步翻译的额外优势。

请记住，当您将数学标记放在 autodoc 读取的**Python 文档字符串**中时，您必须将所有反斜杠加倍，或者使用 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 包 的文档。

当数学只有一行文本时，也可以将其作为指令参数给出。

.. math:: (a + b)^2 = a^2 + 2ab + b^2

选项

:class: 类名 (用空格分隔的类名列表)

分配 类属性。这是一个 常用选项。

:name: 标签 (文本)

一个隐式目标名称，可以使用 ref 进行引用。这是一个 常用选项。

:label: 标签 (文本)

通常，方程式不带编号。如果希望方程式获得编号，请使用 label 选项。给出此选项时，它将为方程式选择一个内部标签，可以通过该标签进行交叉引用，并导致发出方程式编号。请参阅 eq 以获取示例。编号样式取决于输出格式。

:nowrap:

防止将给定的数学内容包装在数学环境中。当您提供此选项时，必须确保您自己正确设置了数学内容。例如

.. math::
   :nowrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

另请参阅

Sphinx 中 HTML 输出的数学支持

使用 HTML 构建器渲染数学的选项。

latex_engine

解释如何配置 LaTeX 构建器以支持数学标记中的 Unicode 字面量。

语法生成显示

可以使用特殊标记来显示形式语法的生成。该标记非常简单，不尝试模拟 BNF（或任何派生形式）的所有方面，但提供了足够的信息，允许以一种将符号的使用呈现为指向符号定义的超链接的方式显示上下文无关语法。有这个指令

.. productionlist:: [productionGroup]

此指令用于包含一组产生式。每个产生式都位于一行上，由一个名称组成，该名称用冒号与后面的定义分隔。如果定义跨越多行，则每行续行必须以冒号开头，冒号的位置与第一行相同。在productionlist指令参数内不允许出现空行。

定义可以包含标记为解释文本的标记名称（例如，“sum ::= `integer` "+" `integer`”）——这会生成到这些标记的产生式的交叉引用。在产生式列表之外，您可以使用token引用标记产生式。

productionlist的productionGroup参数用于区分属于不同语法的不同产生式列表集。因此，具有相同productionGroup的多个产生式列表在相同的范围内定义规则。

在产生式列表内部，标记隐式地引用当前组的产生式。您可以通过在标记前加上其组名和冒号来引用另一个语法的产生式，例如，“otherGroup:sum”。如果不需要在产生式中显示标记的组，则可以在其前加上波浪号，例如，“~otherGroup:sum”。要引用来自未命名语法的产生式，应在标记前加上冒号，例如，“:sum”。

在产生式列表之外，如果您已给出productionGroup参数，则必须在交叉引用中的标记名称前加上组名和冒号，例如，“myGroup:sum”，而不是仅使用“sum”。如果也不希望在链接标题中显示组，则可以提供显式标题（例如，“myTitle <myGroup:sum>”），或者可以在目标前加上波浪号（例如，“~myGroup:sum”）。

请注意，在产生式中不会进行任何进一步的reStructuredText解析，因此您不必转义*或|字符。

以下是从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`

脚注