指令

As previously discussed 指令是显式标记的泛型块。Docutils提供了许多指令，而Sphinx提供了更多指令，并使用指令作为主要的扩展机制之一。

看到 域 对于域添加的角色。

参见

请参阅 reStructuredText Primer 以获取Docutils提供的指令的概述。

目录

由于reStructuredtext不具备互连多个文档或将文档拆分为多个输出文件的功能，因此Sphinx使用自定义指令来添加构成文档的单个文件之间的关系以及内容表。的 toctree 指令是核心要素。

备注

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

备注

要为当前文档（.rst文件）创建目录，请使用标准的reStructuredtext contents directive .

.. toctree::

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

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

考虑这个例子(取自Python文档的库参考索引)：

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

这可以完成两件事：

  • 所有这些文档的目录都被插入，最大深度为两个，这意味着一个嵌套的标题。 toctree 这些文件中的指令也被考虑在内。

  • Sphinx知道文档的相对顺序 intro ， strings 依此类推，并且它知道它们是所显示的文档的子级，即库索引。根据这些信息，它生成“下一章”、“上一章”和“父章”链接。

Entries

文档标题 toctree 将自动从引用文档的标题中读取。如果这不是您想要的，您可以使用与reStructuredtext超链接（和Sphinx的超链接）类似的语法指定显式标题和目标 cross-referencing syntax ).这看起来像：：

.. toctree::

   intro
   All about strings <strings>
   datatypes

上面的第二行将链接到 strings 文档，但将使用标题“All About Strings”而不是 strings 文件。

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

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

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

使用 exclude_patterns 显式地将文档或目录从生成中完全排除。使用 the "orphan" metadata 允许构建文档，但通知Sphinx无法通过toctree访问该文档。

“根文档”（由 root_doc ）是目录树层次结构的“根”。 它可以用作文档的主页，也可以用作“完整目录”（如果您不给出 :maxdepth: 选项.

在 0.6 版本发生变更: 添加了对外部链接和“自我”引用的支持。

选项

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

分配 class attributes .这是一 common option .例如：：

.. toctree::
   :class: custom-toc

Added in version 7.4.

:name: label (text)

可以使用引用的隐式目标名称 ref .这是一 common option .例如：：

.. toctree::
   :name: mastertoc

   foo

Added in version 1.3.

:caption: (text)

在toctree中添加标题。例如：：

.. toctree::
   :caption: Table of Contents

    foo

Added in version 1.3.

:numbered:
:numbered: depth

如果您希望在HTML输出中也有小节号，请添加 :numbered: 选项到 top-level 托特里。例如：：

.. toctree::
   :numbered:

   foo
   bar

然后，部分编号从标题开始 foo .子toctree会自动编号（不要给出 numbered 旗帜到那些）。

通过将深度作为数字参数提供给 numbered 。

Added in version 0.6.

在 1.1 版本发生变更: 添加了数字 depth 论点

:titlesonly:

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

.. toctree::
   :titlesonly:

   foo
   bar

Added in version 1.0.

:glob:

分析toctree条目中的gob外卡。所有条目都与可用文档列表进行匹配，并将匹配项按字母顺序插入到列表中。例如：：

.. toctree::
   :glob:

   intro*
   recipe/*
   *

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

Added in version 0.3.

:reversed:

颠倒列表中条目的顺序。当使用 :glob: 选项.

Added in version 1.5.

:hidden:

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

如果您有其他导航方式（例如，通过手动链接、HTML侧边栏导航或使用 :includehidden: 顶级toctree上的选项。

Added in version 0.6.

:includehidden:

如果您想要一个显示完整文档结构的全局目录，则可以添加 :includehidden: 选项到 top-level toctree指令。然后，可以使用使子页面上的所有其他toctree不可见 :hidden: 选项.顶级toctree与 :includehidden: 然后将包括他们的条目。

Added in version 1.2.

特殊名称

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

特殊文档名称(以及为其生成的页面)为：

  • genindex

    这用于常规索引，其中填充了来自 index 指令和所有索引生成 object descriptions .例如，请参阅Sphinx的 索引 .

  • modindex

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

  • search

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

  • 每个名字以开头 _

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

警告

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

  • 不要使用结肠 : 用于基于HTML的格式。与其他部分的链接可能无法工作。

  • 不要使用plus + 对于ePub格式。有些资源可能找不到。

段级标记

这些指令创建较短的段落，可以在信息单元内部使用，也可以用于普通文本。

警告、信息和警告

警告指令创建了“警告”元素，这是一个传达不同类型信息的标准化系统， tip 至关重要的事情 danger .这些指令可以在普通body元素可以使用的任何地方使用，并且可以包含任意body元素。有九种具体的命名告诫和通用的 admonition 指令。

.. attention::

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

例如：

注意

请注意。

.. caution::

读者应谨慎对待的信息。指令的内容应用完整的句子写成，并包括所有适当的标点符号。

例如：

小心

谨慎行事。

.. danger::

如果不注意，可能会导致附近和现实危险的信息。指令的内容应用完整的句子写成，并包括所有适当的标点符号。

例如：

危险

不要以为要逃避危险，因为爱是自己的复仇者。

.. error::

与某些描述的故障模式相关的信息。指令的内容应用完整的句子写成，并包括所有适当的标点符号。

例如：

错误

错误418：我是茶壶。

.. hint::

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

例如：

提示

看看花盆下面。

.. important::

至关重要且读者不得忽视的信息。指令的内容应用完整的句子写成，并包括所有适当的标点符号。

例如：

重要

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

.. note::

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

例如：

备注

该功能不适合发送垃圾邮件。

.. tip::

为读者提供一些有用的花絮信息。指令的内容应用完整的句子写成，并包括所有适当的标点符号。

例如：

小技巧

别忘了防晒霜！

.. warning::

读者应该非常了解的一个重要信息。指令的内容应用完整的句子写成，并包括所有适当的标点符号。

例如：

警告

小心狗。

.. admonition:: title

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

例如：

这是一个标题

这就是训诫的内容。

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

参见

模块 zipfile

记录本 zipfile 标准模块。

GNU tar manual, Basic Tar Format <https://example.org> _

焦油存档文件的文档，包括NU焦油扩展。

可折叠文本

Added in version 8.2.

每个警告指令都支持 :collapsible: 选项，使警告的内容可折叠（如果输出格式支持）。这对于不总是相关的内容可能很有用。默认情况下，可折叠警告最初是打开的，但可以使用 open 和 closed 的参数 :collapsible: 选项，该选项更改默认状态。在不支持可折叠内容的输出格式中，始终包含文本。例如：

.. 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 [brief explanation]

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

必须提供第一个参数，并且该参数是有问题的版本；您可以添加第二个参数，该参数由 brief 对变更的解释。

注意

指令头和解释之间不能有白线;这是为了使这些块在标记中视觉上连续。

示例：：

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

Added in version 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 ，但描述了该功能何时被弃用。一 brief 也可以给出解释，例如告诉读者使用什么来代替。

示例：：

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

自 3.1 版本弃用: 使用 spam() 而不是.

.. versionremoved:: version [brief explanation]

类似于 versionadded ，但描述了该功能何时被删除。可能会提供解释来告诉读者要使用什么，或者为什么删除该功能。

Added in version 7.3.

示例：：

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

Removed in version 4.0: 的 spam() 功能更灵活，应该改用。

表象

.. rubric:: title

一个标题就像一个非正式的标题，它不对应于文档的结构，也就是说，它不创建一个目录节点。

备注

如果 title 如果引语是“脚注”(或所选语言的等价物)，则 Latex 作者会忽略该引语，因为假定该引语只包含脚注定义，因此会创建一个空标题。

选项

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

分配 class attributes .这是一 common option .

:name: label (text)

可以使用引用的隐式目标名称 ref .这是一 common option .

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

Added in version 7.4.1.

使用此选项指定标题级别。在这种情况下，标题将呈现为 <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

Added in version 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

  • ..。以及任何其他 lexer alias that Pygments supports

如果用所选语言高亮显示失败(即Pygments发出“ERROR”标记)，则不会以任何方式突出显示该块。

重要

支持的词法分析器别名列表与Pygment版本相关。如果你想确保一致的高亮显示，你应该修正你的俾格森版本。

.. highlight:: language

示例：：

.. highlight:: c

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

选项

:linenothreshold: threshold (number (optional))

启用以生成代码块的行号。

此选项采用可选数字作为阈值参数。如果给定任何阈值，该指令将只为长度超过N行的代码块生成行号。如果未指定，则将为所有代码块生成行号。

示例：：

.. highlight:: python
   :linenothreshold: 5
:force: (no value)

如果给定，突出显示的小错误将被忽略。

Added in version 2.1.

.. code-block:: [language]
.. sourcecode:: [language]
.. code:: [language]

示例：：

.. code-block:: ruby

   Some Ruby code.

指令的别名 sourcecode 也很管用。此指令以语言名称作为参数。它可以是 any lexer alias supported by Pygments 。如果未给出，则 highlight 指令将被使用。如果未设置， highlight_language 将会被使用。显示代码示例 inline 在其他文本中，而不是作为单独的块，可以使用 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.

Added in version 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.')

Added in version 1.1.

在 1.6.6 版本发生变更: LaTeX支持 emphasize-lines 选择。

:force: (no value)

忽略突出显示时的小错误。

Added in version 2.1.

:caption: caption of code block (text)

设置代码块的标题。

Added in version 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.

Added in version 1.3.

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

分配 class attributes .这是一 common option .

Added in version 1.4.

:dedent: number (number or no value)

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

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

       some ruby code

Added in version 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 .这是一 common option .

Added in version 1.4.

:name: label (text)

可以使用引用的隐式目标名称 ref .这是一 common option .

Added in version 1.3.

:caption: caption (text)

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

Added in version 1.3.

格式选项

:dedent: number (number or no value)

从包含的内容中删除凹痕字符。当给定数字时，会删除开头的N个字符。当没有给出参数时，所有常见的引导凹痕都会被删除（使用 textwrap.dedent() ).

Added in version 1.3.

在 3.5 版本发生变更: 支持自动定位器。

:tab-width: N (number)

将选项卡扩展到N个空间。

Added in version 1.0.

:encoding: (text)

明确指定文件的编码。这会覆盖默认编码 (source_encoding ).例如：

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

Added in version 0.4.3.

:linenos: (no value)

在包含的内容旁边显示卡号。默认情况下，行号从1开始计数。这可以通过选项更改 :lineno-start: 和 :lineno-match: .

:lineno-start: number (number)

设置要显示的第一行的卡号。如果给出，这将自动激活 :linenos: .

:lineno-match:

当仅包括文件的部分内容并显示原始的行号时。只有当选择内容由连续的线组成时才允许这样做。

Added in version 1.3.

:emphasize-lines: line numbers (comma separated numbers)

强调所包含内容的特定行。例如：

.. literalinclude:: example.txt
   :emphasize-lines: 1,2,4-6
:language: language (text)

选择突出显示语言 (Pygments lexer ）与当前文件的标准语言不同（由 highlight 或 highlight_language ).

:force: (no value)

忽略突出显示时的小错误。

Added in version 2.1.

用于选择要包含的内容的选项

:pyobject: object (text)

对于Python文件，仅包括指定的类、函数或方法：

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

Added in version 0.6.

:lines: line numbers (comma separated numbers)

准确指定要包括哪些行：：

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

这包括第1行、第3行、第5行到第10行，以及第20行到末尾。

Added in version 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 跳过第一行）。

Added in version 0.6: 添加了 start-after 和 end-before 选项.

Added in version 1.5: 添加了 start-at ，以及 end-at 选择。

小技巧

仅选择 [second-section] 对于诸如以下这样的DID文件，使用 :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 或 ?> 标记。

Added in version 1.0.

:append: line (text)

在包含的代码后面添加一行。例如，当突出显示不包括 <?php 或 ?> 标记。

Added in version 1.0.

:diff: filename

显示两个文件的差异。例如：

.. literalinclude:: example.txt
   :diff: example.txt.orig

这显示了两者之间的差异 example.txt 和 example.txt.orig 具有统一的差异格式。

Added in version 1.3.

在 0.6 版本发生变更: 添加了对绝对文件名的支持。

在 1.6 版本发生变更: 两者都有 start-after 和 lines 在使用中，第一行根据 start-after 被认为与行号相同 1 为 lines 。

词汇表

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

与常规定义列表不同， multiple 允许每个条目的术语，并允许术语中的内联标记。您可以链接到所有术语。例如：：

.. glossary::

   term 1
   term 2
      Definition of both terms.

(对词汇表进行排序时，第一个术语确定排序顺序。)

如果您想为普通索引项指定“GROUPING KEY”，则可以将“KEY”设置为“Term：Key”。例如：：

.. glossary::

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

请注意，“key”用于按原样分组key。“键”未规范化；键“A”和“a”成为不同的组。“key”中的整个字符用来代替第一个字符；它用于“组合字符序列”和“代理对”分组键。

在I18N情况下，即使原始文本只有“Term”部分，也可以指定“Localized Term：Key”。在这种情况下，翻译后的“本地化术语”将归入“关键字”组。

在 1.1 版本发生变更: 现在支持多个术语和术语中的内联标记。

在 1.4 版本发生变更: 应考虑术语表术语的索引键 experimental 。

选项

:sorted:

按字母顺序对条目进行排序。

Added in version 0.6.

在 4.4 版本发生变更: 在国际化文档中，根据翻译后的术语排序。

元信息标记

.. sectionauthor:: name <email>

标识当前节的作者。参数应包括作者的姓名，以便可以用于演示文稿和电子邮件地址。地址的域名部分应为小写。示例：：

.. sectionauthor:: Guido van Rossum <guido@python.org>

默认情况下，此标记不会以任何方式反映在输出中(它有助于跟踪贡献)，但您可以设置配置值 show_authors 至 True 让他们在输出中产生一个段落。

.. codeauthor:: name <email>

这个 codeauthor 指令可以多次出现，它指定所描述代码的作者，就像 sectionauthor 说出一篇文献的作者(S)的名字。它也只在以下情况下才产生输出 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
---------------------

...

此指令包含五个条目，它们将被转换为生成的索引中的条目，这些条目链接到INDEX语句的确切位置(或在脱机媒体的情况下，链接到相应的页码)。

由于索引指令在它们在源代码中的位置生成交叉引用目标，因此将它们放入 before 他们所指的东西--例如，上面的例子中的标题。

可能的条目类型包括：

单人

创建单个索引项。可以通过用分号分隔子条目文本来使其成为子条目(下面还使用该符号来描述创建了什么条目)。例如：

.. index:: single: execution
           single: execution; context

  • single: execution 创建带标签的索引项 execution 。

  • single: execution; context 创建以下项的子项 execution 已贴标签 context 。

成对

创建两个索引项的快捷方式。这对值必须用分号分隔。示例：

.. index:: pair: loop; statement

这将创建两个索引项； loop; statement 和 statement; loop 。

三重

创建三个索引项的快捷方式。所有三个值都必须用分号分隔。示例：

.. index:: triple: module; search; path

这将创建三个索引项； module; search path ， search; path, module ，以及 path; module search 。

看见

创建引用另一个条目的索引项的快捷方式。示例：

.. index:: see: entry; other

这将创建一个引用 entry 至 other (即“条目”：见“其他”)。

另请参阅

喜欢 see ，但插入“See Also”而不是“See”。

模块、关键字、运算符、对象、异常、语句、构建

这些 deprecated 所有快捷方式都会创建两个索引项。例如, module: hashlib 创建条目 module; hashlib 和 hashlib; module 。

自 1.0 版本弃用: 这些特定于Python的条目类型已弃用。

在 7.1 版本发生变更: 删除版本设置为Sphinx 9.0。现在使用这些条目类型将发出警告，并显示 index 类别。

您可以通过在“主”索引项前面加上感叹号来标记这些索引项。在生成的索引中强调了对“主”条目的引用。例如，如果两个页面包含：：

.. index:: Python

其中一页包含：

.. index:: ! Python

然后在三个反向链接中强调到后一个页面的反向链接。

对于只包含“单个”条目的索引指令，有一个速记符号：：

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

这将创建四个索引项。

在 1.1 版本发生变更: 增列 see 和 seealso 类型，以及标记主要条目。

选项

:name: a label for hyperlink (text)

定义可通过使用引用的隐式目标名称 ref 。例如：：

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

Added in version 3.0.

:index:

而当 index 指令是块级标记并链接到下一段的开头，也有一个相应的角色直接设置使用它的链接目标。

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

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

Added in version 1.1.

包括基于标签的内容

.. only:: <expression>

包括指令的内容，仅当 expression 是真的。该表达式应由标记组成，如下所示：：

.. only:: html and draft

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

这个 format 以及 name 当前构建者的 (html ， latex 或 text )始终设置为标记 [4]. 为了明确区分格式和名称，它们还添加了前缀 format_ 和 builder_ 例如，epub构建器定义标签 html ， epub ， format_html 和 builder_epub 。

这些标准标签已设置 after 配置文件已读取，因此它们在那里不可用。

所有标签必须遵循标准的Python标识符语法，如 Identifiers and keywords 文件。也就是说，标记表达式可能只由符合Python变量语法的标记组成。在ASCII中，这由大写字母和小写字母组成 A 穿过 Z ，下划线 _ 并且，除第一个字符外，数字 0 穿过 9 。

Added in version 0.6.

在 1.2 版本发生变更: 添加了建造者的名称和前缀。

警告

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

表格

使用 reStructuredText tables ，即任一

这个 table 指令充当可选的 grid 和 simple 语法。

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

在 1.6 版本发生变更: 从包含复杂内容的网格表(如多个段落、块引号、列表、文字块)中合并的单元格(多行、多列，两者)将正确地呈现为LaTeX输出。

.. tabularcolumns:: column spec

该指令只影响SOURCE中下一个表的LaTeX输出。强制参数是列规范(在LaTeX习惯用法中称为“对齐前导”)。请参阅LaTeX文档，如 wiki page ，了解此类柱规格的基础知识。

Added in version 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 柱类型。然后，列类型必须是某个 p{width} 使用显式 width (或 \X{a}{b} 或 \Y{f} )。

  • 文字块不适用于 tabulary 完全没有。Sphinx将退回到 tabular 或 longtable 环境，并生成合适的柱规格。

在缺少 tabularcolumns 指令，并且对于上面警告中描述的最多包含30行且没有问题单元格的表，Sphinx使用 tabulary 以及 J 列-每列的类型。

在 1.6 版本发生变更: 以前， L 使用了列型(文本左对齐)。要恢复到这一点，请包括 \newcolumntype{T}{L} 在LaTeX的序言中，Sphinx实际上使用了 T 并将其默认设置为的别名 J 。

提示

一个常见的问题是 tabulary 内容很少的栏目似乎被“挤压”了。例如，可以添加到 Latex 前导码 \setlength{\tymin}{40pt} 以确保最小列宽为 40pt vt.的. tabulary 默认为 10pt 太小了。

提示

强制使用 Latex longtable 环境通行证 longtable 作为一名 :class: 选项以 table ， csv-table ，或 list-table 。使用 rst-class 对于其他桌子。

数学

数学的输入语言是LaTeX标记。这是纯文本数学表示法的事实标准，并且还有一个额外的优势，即在构建LaTeX输出时不需要进一步的转换。

请记住，在将数学标记放入 Python docstrings 阅读者 autodoc ，您要么必须将所有反斜杠都加倍，要么使用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 .这是一 common option .

:name: label (text)

可以使用引用的隐式目标名称 ref .这是一 common option .

:label: label (text)

通常情况下，方程式是不编号的。如果希望您的方程式得到一个数字，请使用 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 (or任何派生形式），但提供的内容足以允许以导致符号的使用被呈现为符号定义的超链接的方式显示上下文无关语法。有这个指令：

.. productionlist:: [production_group]

此指令用于封闭一组产品。每个生成都在一行中给出，并由一个名称组成，并由下面的定义中的逗号隔开。如果定义跨越多行，则每条续行必须以与第一行相同的列上的斜线开始。内不允许有白线 productionlist 指令性论点。

任择 production_group 指令参数用于区分属于不同语法的不同生产列表集。多个生产列表， production_group 从而定义同一范围内的规则。这还可以用于将长或复杂语法的描述拆分为多个 productionlist 指令与相同的 production_group .

该定义可以包含标记为解释文本的标记名称，（例如“' 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`

脚注