段落级标记

这些指令创建短的段落，并且可以在信息单元以及正常文本中使用：

.. note::

关于API的一个特别重要的信息，用户在使用该注释所涉及的任何API时应该注意。指令的内容应以完整的句子写成，并包括所有适当的标点符号。

例：

.. note::

   This function is not suitable for sending spam e-mails.
.. warning::

有关API的一个重要信息，用户在使用警告所涉及的任何API时应该非常注意。指令的内容应以完整的句子写成，并包括所有适当的标点符号。这与note不同的是，建议它记录note以外的有关安全性的信息。

.. versionadded:: version

此指令记录将描述的功能添加到库或C API的项目版本。当这运用于整个模块时，应将其放在模块部分的顶部，在任何段落之前。

第一个参数必须给出，并且是所讨论的版本；你可以添加第二个参数，由简要的更改说明组成。

例：

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

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

.. versionchanged:: version

类似于versionedded，但描述指明的功能所更改的时间和内容（新参数、更改的副作用等）。

.. deprecated:: version

与versionchanged类似，但描述该功能已弃用的时间。还可以给出解释，例如通知读者应当使用什么。例：

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

许多小节包括对模块文档或外部文档的引用列表。这些列表是使用seealso指令创建的。

seealso指令通常放置在任何子小节之前的段落中。对于HTML输出，它显示在从文本的主流之外。

seealso指令的内容应为reST定义列表。例：

.. seealso::

   Module :py:mod:`zipfile`
      Documentation of the :py:mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

还允许一个“简短形式”，看起来像这样：

.. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

版本0.5中的新功能：简短形式。

.. rubric:: title

此指令创建段落标题，它们不用于创建目录。

注意

如果Rubric的title为“Footnotes”（或所选语言的等效项），则LaTeX writer将忽略此Rubric，因为它假定仅包含脚注定义，因此将创建空标题。

.. centered::

此指令创建一个居中的粗体文本行。使用方法如下：

.. centered:: LICENSE AGREEMENT

自从1.1版起已弃用：这个只用于显示的指令是从旧版本的遗留下来的。请改用rst-class指令，并添加相应的样式。

.. hlist::

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

对于支持水平分布的构建器，有一个columns选项，用于指定列数；它默认为2。Example:

.. hlist::
   :columns: 3

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

版本0.6中的新功能。

目录标记

toctree指令，它生成子文档的目录，在TOC树中描述。

对于本地目录，请使用标准的reST contents指令。

词汇表

.. glossary::

此指令必须包含带有术语和定义的reST定义列表式标记。然后，可以使用term角色来引用定义。Example:

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

注意，“key”用于按原样分组键。“键”未标准化；键“A”和“a”变成不同的组。使用“键”中的整个字符而不是第一个字符；它用于“组合字符序列”和“代理对”分组键。

在i18n情况下，即使原始文本只有“term”部分，也可以指定“localized term:key”。在这种情况下，翻译的“本地化术语”将被分类在“键”组中。

版本0.6中的新功能：现在可以为词汇表指令提供:sorted:标志，将按字母顺序自动对条目进行排序。

在版本1.1中更改：现在支持多个术语和内联标记。

在版本1.4中更改：词汇表术语的索引键应视为实验性的。

语法产生式的显示

特殊标记可用于显示形式语法。该标记很简单，并且不尝试对BNF（或任何派生形式）的所有方面建模，但是提供足够的以允许以使得将符号的使用呈现为定义的超链接的方式显示上下文无关语法的符号。就是这个指令：

.. productionlist:: [name]

该指令用于包含一组产生式。每个产生式在一行上给出，由一个名称组成，用下面定义的冒号分隔。如果定义跨多行，每个连续行必须以冒号放在与第一行相同的列处开头。

productionlist的参数用于区分属于不同语法的不同的产生式列表集合。

productionlist指令参数中不允许有空行。

定义可以包含符号名称，它们被标记为可解释的文本（例如sum ::= `integer` "+" `integer`） - 这会生成对这些标记产生式的交叉引用。在产生式列表之外，你可以使用token引用token产生式。

注意，在产生式中不进行进一步的reST解析，所以你不必转义*或|字符。

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