指令

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

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

另请参阅

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

目录

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

注意

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

注意

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

.. toctree::

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

“TOC 树”的表示形式在每种输出格式中都会更改。输出多个文件（例如 HTML）的构建器将其视为超链接的集合。另一方面，输出单个文件（例如 LaTeX、man 页面等）的构建器将其替换为 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 文档，但将使用标题“All about strings”而不是 strings 文档的标题。

您还可以添加外部链接，方法是提供 HTTP URL 而不是文档名称。

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

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

使用 exclude_patterns 来显式排除文档或目录完全构建。 使用“orphan”元数据让文档被构建，但通知 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 会自动编号（不要为这些子 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 指令。然后可以使用 :hidden: 选项使子页面上的所有其他 toctree 不可见。带有 :includehidden: 的顶层 toctree 将包含它们的条目。

在 1.2 版本中添加。

特殊名称

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

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

  • genindex

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

  • modindex

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

  • search

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

  • 每个以 _ 开头的名称

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

警告

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

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

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

段落级标记

这些指令创建短段落，可以用于信息单元以及普通文本。

告诫，消息和警告

告诫指令创建“告诫”元素，这是一个标准化的系统，用于传达不同类型的信息，从有用的提示到至关重要的危险。这些指令可以用于任何普通正文元素可以使用的位置，并且可以包含任意正文元素。有九个特定的命名告诫和通用的 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 扩展。

可折叠文本

在 8.2 版本中添加。

每个告诫指令都支持 :collapsible: 选项，以使告诫的内容可折叠（在输出格式支持的情况下）。这对于并非始终相关的内容可能很有用。默认情况下，可折叠的告诫最初是打开的，但这可以通过 :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.
注意

此注释是可折叠的，默认情况下最初是打开的。

例子

此示例是可折叠的，最初是打开的。

提示

此提示是可折叠的，但最初是关闭的。

描述版本之间的更改

.. versionadded:: version [简要说明]

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

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

注意

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

例子

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

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

.. versionchanged:: version [简要说明]

类似于 versionadded，但描述了命名功能在某些方面发生更改的时间和内容（新参数、更改的副作用等）。

例子

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

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

.. deprecated:: version [简要说明]

类似于 versionadded，但描述了该功能何时被弃用。也可以给出简要说明，例如告诉读者改用什么。

例子

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

在 3.1 版本中弃用: 请改用 spam()。

.. versionremoved:: version [简要说明]

类似于 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 的标题是“Footnotes”（或所选语言的等效项），则 LaTeX 编写器会忽略此 rubric，因为它被假定仅包含脚注定义，因此会创建空标题。

选项

:class: class names （类名列表，以空格分隔）

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

:name: label （文本）

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

:heading-level: n （从 1 到 6 的数字）

在 7.4.1 版本中添加。

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

.. centered::

此指令创建居中粗体文本行。

在 1.1 版本中弃用: 此仅用于演示的指令是旧版本的遗留物。请改用 rst-class 指令并添加适当的样式。

.. hlist::

此指令必须包含项目符号列表。它将通过水平分布多个项目或减少项目之间的间距，将其转换为更紧凑的列表，具体取决于构建器。

选项

:columns: n （整数）

列数；默认为 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 支持的任何其他 lexer 别名

如果使用选定的语言进行高亮失败 (即 Pygments 发出 “Error” 令牌)，则代码块将不会以任何方式高亮显示。

重要

支持的词法分析器别名列表与 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 选项。

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

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

在 1.4 版本中添加。

:dedent: number (number or no value)

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

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

       some ruby code

在 1.3 版本中添加。

在 3.5 版本中更改: 支持自动 dedent。

.. literalinclude:: filename

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

.. literalinclude:: example.py

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

通用选项

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

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

在 1.4 版本中添加。

:name: label (text)

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

在 1.3 版本中添加。

:caption: caption (text)

在包含的内容上方添加标题。如果未给出参数，则文件名将用作标题。

在 1.3 版本中添加。

格式化选项

:dedent: number (number or no value)

从包含的内容中去除缩进字符。当给出数字时，将删除前 N 个字符。当未给出参数时，将删除所有常见的前导缩进 (使用 textwrap.dedent())。

在 1.3 版本中添加。

在 3.5 版本中更改: 支持自动 dedent。

:tab-width: N (number)

将制表符展开为 N 个空格。

在 1.0 版本中添加。

:encoding: (text)

显式指定文件的编码。这将覆盖默认编码 (source_encoding)。例如

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

选择与当前文件的标准语言不同的高亮语言 (Pygments 词法分析器) (由 highlight 或 highlight_language 设置)。

: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

这以统一的 diff 格式显示 example.txt 和 example.txt.orig 之间的差异。

在 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” 未标准化；键 “A” 和 “a” 成为不同的组。使用 “key” 中的所有字符而不是第一个字符；它用于 “组合字符序列” 和 “代理对” 分组键。

在 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 创建一个标记为 context 的 execution 的子条目。

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 类别的警告。

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

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

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

.. only:: html and draft

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

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

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

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

在 0.6 版本中添加。

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

警告

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

表格

使用 reStructuredText 表格，即以下任一种：

table 指令充当 grid 和 simple 语法的可选包装器。

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

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

.. tabularcolumns:: 列 规格

此指令仅影响源中下一个表格的 LaTeX 输出。强制性参数是列规格（在 LaTeX 习语中称为“对齐前导码”）。请参阅 LaTeX 文档，例如 wiki 页面，了解此类列规格的基础知识。

在 0.3 版本中添加。

注意

tabularcolumns 与表格指令的 :widths: 选项冲突。如果两者都指定，则 :widths: 选项将被忽略。

Sphinx 将渲染超过 30 行的表格，使用 longtable。除了 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} 的效果（即，每个单元格都是 LaTeX \parbox），具有指定的内部文本对齐方式和自动计算的 width。

警告

  • 包含类似列表元素（如对象描述、块引用或任何类型的列表）的单元格与 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 的一个常见问题是内容很少的列显得“挤压”。可以添加到 LaTeX 前导码中，例如 \setlength{\tymin}{40pt}，以确保最小列宽为 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。编号样式取决于输出格式。

: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 构建器以支持数学标记中的 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”。标准 交叉引用修饰符 可以与 :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`

脚注