reStructuredText 标记

本文档介绍了 Sphinx 引入的用于支持 Python 文档的自定义 reStructuredText 标记，以及如何使用它。

快速参考

此表总结了哪些标记应用于一些常用元素

元素	标记	另请参阅
参数/参数	*arg*	内联标记
变量/文字/代码	``foo``, ``42``, ``len(s) - 1``	内联标记
真/假/无	``True``, ``False``, ``None``	内联标记
函数定义	.. function:: print(*args)	指令
函数引用	:func:`print`	角色
属性定义	.. attribute: `attr-name`	信息单元
属性引用	:attr:`attr-name`	角色
引用标签	.. _label-name:	交叉链接标记
内部引用	:ref:`label-name`	交叉链接标记
外部链接	`Link text <https://example.com>`_	超链接
带自定义文本的角色	:role:`custom text <target>`	角色
仅带最后一部分的角色	:role:`~hidden.hidden.visible`	角色
无链接的角色	:role:`!target`	角色
问题	:gh:`ID`, :issue:`ID`	角色
CPython 源	:source:`PATH`	角色
注释	.. a comment	注释

reStructuredText 入门

本节简要介绍 reStructuredText (reST) 概念和语法，旨在为作者提供足够的信息以高效地撰写文档。由于 reST 被设计为一种简单、不显眼的标记语言，因此不会花费太长时间。

另请参阅

权威的 reStructuredText 用户文档。

空白的使用

所有 reST 文件都使用 3 个空格的缩进；不允许使用制表符。普通文本的最大行长为 80 个字符，但表格、深度缩进的代码示例和长链接可能会超出此长度。代码示例主体应使用常规 Python 4 个空格缩进。

在适用的情况下使用多个空行来阐明 reST 文件的结构。额外的空行有助于将部分分组在一起，使文件的组织更清晰。

句末句号后面可以跟一个或两个空格。虽然 reST 忽略第二个空格，但一些用户习惯性地输入它，例如为了帮助 Emacs 的自动填充模式。

段落

段落是 reST 文档中最基本的块。段落只是由一个或多个空行分隔的文本块。与 Python 中一样，缩进在 reST 中很重要，因此同一段落的所有行都必须左对齐到相同的缩进级别。

内联标记

标准 reST 内联标记非常简单：使用

• 一个星号：*text* 表示强调（斜体），

• 两个星号：**text** 表示强强调（粗体），以及

• 反引号：``text`` 表示代码示例、变量和文字。

如果星号或反引号出现在正文中，并且可能与内联标记分隔符混淆，则必须使用反斜杠对其进行转义。

请注意此标记的一些限制

• 它不能嵌套，

• 内容不能以空格开头或结尾：* text* 是错误的，

• 它必须用非单词字符与周围文本分隔。使用反斜杠转义的空格来解决此问题：thisis\ *one*\ word。

这些限制可能会在 docutils 的未来版本中解除。

reST 还允许使用自定义“解释文本角色”，表示应以特定方式解释所包含的文本。Sphinx 使用它来提供语义标记和标识符的交叉引用，如相应部分中所述。一般语法是 :rolename:`content`。

列表和引用

列表标记是自然的：只需在段落开头放置一个星号并正确缩进即可。带编号的列表也是如此；它们还可以使用 # 符号自动编号

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

嵌套列表是可能的，但请注意，它们必须用空行与父列表项分隔

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

定义列表的创建方式如下

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

段落只需比周围的段落缩进更多即可引用。

源代码

通过用特殊标记 :: 结束段落来引入文字代码块。文字块必须缩进

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

对 :: 标记的处理很智能

• 如果它作为自己的段落出现，则该段落将完全从文档中省略。

• 如果它前面有空格，则删除该标记。

• 如果它前面没有空格，则该标记将替换为单个冒号。

这样，上面示例的第一段中的第二句话将呈现为“下一段是代码示例：”。

超链接

外部链接

对于内联网络链接，请使用 `Link text <http://target>`_。如果链接文本应该是网络地址，则根本不需要特殊标记，解析器会在普通文本中查找链接和邮件地址。

内部链接

内部链接通过特殊的 reST 角色完成，请参阅特定标记部分，交叉链接标记。

部分

通过用标点符号对节标题加下划线（和可选的上划线）来创建节标题，至少与文本一样长

=================
This is a heading
=================

通常，不会将标题级别分配给某些字符，因为结构是由标题的连续性决定的。但是，对于 Python 文档，这里有一个建议的约定

• # 带上划线，用于部分

• * 带上划线，用于章节

• =，用于节

• -，用于小节

• ^，用于子小节

• "，用于段落

显式标记

在 reST 中，对于大多数需要特殊处理的构造（例如脚注、特别突出显示的段落、注释和通用指令）使用“显式标记”。

显式标记块以 .. 开头的行开头，后面是空格，并以相同缩进级别的下一个段落结尾。（显式标记和普通段落之间需要有一个空行。这听起来可能有点复杂，但当你写它时，它足够直观。）

指令

指令是显式标记的通用块。除了角色之外，它还是 reST 扩展机制之一，Sphinx 大量使用它。

基本上，一个指令由名称、参数、选项和内容组成。（记住这个术语，它用于下一节中描述自定义指令。）查看此示例，

.. function:: foo(x)
              foo(y, z)
   :bar: no

   Return a line of text input from the user.

function 是指令名称。这里给它两个参数，第一行的其余部分和第二行，以及一个选项 bar（如您所见，选项在参数之后的行中给出，并用冒号表示）。

指令内容紧随空行之后，并且相对于指令开头缩进。

脚注

对于脚注，使用 [#]_ 标记脚注位置，并在“脚注”标题标题下方的文档底部添加脚注正文，如下所示

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

您还可以明确编号脚注以获得更好的上下文。

注释

每个显式标记块（以 .. 开头）都不是 有效的标记结构，则视为注释

.. This is a comment

源编码

由于在 reST 中包含特殊字符（如 em 破折号或版权符号）的最简单方法是直接将其写为 Unicode 字符，因此必须指定编码

所有 Python 文档源文件都必须采用 UTF-8 编码，并且从中编写的 HTML 文档也将采用该编码。

陷阱

在编写 reST 文档时，通常会遇到一些问题

• 内联标记的分隔：如上所述，内联标记跨度必须通过非单词字符与周围文本分隔，您必须使用转义空格来解决此问题。

印刷惯例

大 O 符号

大 O 符号用于描述算法的性能。

为大 O 和变量使用斜体。例如

reStructuredText	渲染
*O*\ (1)	O(1)
*O*\ (log *n*)	O(log n)
*O*\ (*n*)	O(n)
*O*\ (*n* log *n*)	O(n log n)
*O*\ (*n*\ :sup:`2`)	O(n2)

其他标记结构

Sphinx 为标准 reST 标记添加了许多新指令和解释文本角色。本节包含这些工具的参考材料。此处不包括“标准”reST 结构的文档，尽管它们用于 Python 文档中。

注意

这只是 Sphinx 扩展标记功能的概述；可以在 其自己的文档 中找到完整内容。

元信息标记

sectionauthor

标识当前部分的作者。参数应包括作者的姓名，以便可用于演示（尽管它不是）和电子邮件地址。地址的域名部分应为小写。示例

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

目前，此标记不会以任何方式反映在输出中，但有助于跟踪贡献。

特定于模块的标记

本节中描述的标记用于提供有关正在记录的模块的信息。每个模块都应在其自己的文件中记录。通常，此标记出现在该文件的标题标题之后；一个典型的文件可能像这样开始

:mod:`parrot` -- Dead parrot access
===================================

.. module:: parrot
   :platform: Unix, Windows
   :synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

如您所见，特定于模块的标记由两个指令组成，即 module 指令和 moduleauthor 指令。

module

此指令标记模块、包或子模块的描述的开头。名称应完全限定（即对于子模块包括包名称）。

如果存在 platform 选项，则它是模块可用的平台的逗号分隔列表（如果它在所有平台上可用，则应省略该选项）。键是简短的标识符；正在使用的示例包括“IRIX”、“Mac”、“Windows”和“Unix”。在适用时使用已经使用过的键非常重要。

synopsis 选项应包含一句描述模块用途的句子 - 它目前仅在全局模块索引中使用。

deprecated 选项可用于将模块标记为已弃用（无值）；然后它将在各个位置被指定为已弃用。

moduleauthor

moduleauthor 指令可多次出现，它指定模块代码的作者，就像 sectionauthor 指定文档作者一样。它目前也不会产生任何输出。

注意

模块描述文件的小节标题很重要，因为该值将插入概述文件中的目录树中。

信息单元

有一些指令用于描述模块提供的特定功能。每个指令需要一个或多个签名来提供有关所描述内容的基本信息，内容应为描述。基本版本会在通用索引中创建条目；如果您不希望创建索引条目，则可以提供指令选项标志 :noindex:。以下示例显示了此指令类型的全部功能

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

对象方法或数据属性的签名不应包含类名，但应嵌套在类指令中。生成的文件将反映此嵌套，目标标识符（对于 HTML 输出）将使用类名和方法名，以启用一致的交叉引用。如果您描述属于抽象协议（例如上下文管理器）的方法，也请使用具有（伪）类型名的类指令，以使索引条目更具信息性。

指令为

c:function

描述 C 函数。签名应按 C 中的方式给出，例如

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

这也用于描述类似函数的预处理器宏。应给出参数的名称，以便在描述中使用它们。

请注意，您不必对签名中的星号进行反斜杠转义，因为它不是由 reST 内联解析器解析的。

c:member

描述 C 结构成员。示例签名

.. c:member:: PyObject* PyTypeObject.tp_bases

描述的文本应包括允许的值范围、如何解释该值以及该值是否可以更改。文本中对结构成员的引用应使用 member 角色。

c:macro

描述“简单”的 C 宏。简单宏是用于代码扩展的宏，但它不接受参数，因此无法描述为函数。这不适用于简单的常量定义。它在 Python 文档中的使用示例包括 PyObject_HEAD 和 Py_BEGIN_ALLOW_THREADS。

c:type

描述 C 类型。签名应仅为类型名。

c:var

描述全局 C 变量。签名应包括类型，例如

.. c:var:: PyObject* PyClass_Type

data

描述模块中的全局数据，包括用作“已定义常量”的变量和值。类和对象属性不使用此指令进行记录。

exception

描述异常类。签名可以包含构造函数参数的括号，但不是必须的。

function

描述模块级函数。签名应包括参数，将可选参数括在括号中。如果能增强清晰度，则可以给出默认值。例如

.. function:: repeat([repeat=3[, number=1000000]])

对象方法不使用此指令进行记录。作为模块公共接口的一部分放置在模块命名空间中的绑定对象方法使用此指令进行记录，因为它们在大多数情况下等同于普通函数。

描述应包括有关所需参数的信息以及如何使用它们（尤其是是否修改了作为参数传递的可变对象）、副作用和可能的异常。可以提供一个小示例。

coroutinefunction

描述模块级协程。描述应包括与为 function 描述的类似信息。

decorator

描述装饰器函数。签名不应表示实际函数的签名，而是作为装饰器的用法。例如，给定以下函数

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

描述应如下所示

.. decorator:: removename

   Remove name of the decorated function.

.. decorator:: setnewname(name)

   Set name of the decorated function to *name*.

没有 deco 角色可链接到用此指令标记的装饰器；相反，使用 :func: 角色。

class

描述一个类。签名可以包括带参数的括号，这些参数将显示为构造函数参数。

attribute

描述对象数据属性。描述应包括有关预期的数据类型以及是否可以直接更改该类型的信息。此指令应嵌套在类指令中，如下例所示

.. class:: Spam

   Description of the class.

   .. attribute:: ham

      Description of the attribute.

使用 :attr: 角色引用属性

Use the :attr:`ham` attribute to spam the eggs.

如果在类指令之外记录属性也是可能的，例如，如果不同属性和方法的文档被拆分为多个部分。然后应明确包括类名

.. attribute:: Spam.eggs

method

描述对象方法。参数不应包括 self 参数。描述应包括与 function 描述中类似的信息。此指令应嵌套在类指令中，如上例所示。

coroutinemethod

描述对象协程方法。参数不应包括 self 参数。描述应包括与 function 描述中类似的信息。此指令应嵌套在 class 指令中。

decoratormethod

与 decorator 相同，但适用于方法装饰器。

使用 :meth: 角色引用装饰器方法。

staticmethod

描述对象静态方法。描述应包括与 function 描述中类似的信息。此指令应嵌套在 class 指令中。

classmethod

描述对象类方法。参数不应包括 cls 参数。描述应包括与 function 描述中类似的信息。此指令应嵌套在 class 指令中。

abstractmethod

描述对象抽象方法。描述应包括与 function 描述中类似的信息。此指令应嵌套在 class 指令中。

opcode

描述 Python 字节码 指令。

option

描述 Python 命令行选项或开关。选项参数名称应放在尖括号中。示例

.. option:: -m <module>

   Run a module as a script.

envvar

描述 Python 使用或定义的环境变量。

这些指令还有一个通用版本

describe

此指令生成与上述特定指令相同的格式，但不创建索引条目或交叉引用目标。例如，它用于描述本文档中的指令。示例

.. describe:: opcode

   Describes a Python bytecode instruction.

显示代码示例

使用标准 reST 字面量块表示 Python 源代码或交互式会话的示例。它们以前一段末尾的 :: 开始，并以缩进分隔。

表示交互式会话需要包括提示和输出以及 Python 代码。交互式会话不需要特殊标记。在输入或输出的最后一行显示后，不应有尾随提示。正确用法的示例是

>>> 1 + 1
2

语法高亮以智能方式处理

• 每个源文件都有一个“突出显示语言”。默认情况下，这是 'python'，因为大多数文件都必须突出显示 Python 片段。

• 在 Python 突出显示模式中，交互式会话会自动识别并适当地突出显示。

• 可以使用 highlight 指令更改突出显示语言，用法如下

  .. highlight:: c
  

  此语言将一直使用，直到遇到下一个 highlight 指令。

• 可以使用 code-block 指令指定单个代码块的突出显示语言，例如

  .. code-block:: c
  
     #include <stdio.h>
  
     void main() {
         printf("Hello world!\n");
     }
  

• 通常用于突出显示语言的值有

  • python（默认值）

  • c

  • rest

  • none（不突出显示）

• 如果使用当前语言突出显示失败，则不会以任何方式突出显示该块。

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

.. literalinclude:: example.py

文件名相对于当前文件的路径。特定于文档的包含文件应放在 Doc/includes 子目录中。

注意

有一个标准的 include 指令，但如果找不到文件，它会引发错误。首选 literalinclude，因为它只会发出警告，而不是引发错误。

角色

正如 前面提到的，Sphinx 使用 :rolename:`content` 形式的解释文本角色在文档中插入语义标记。

在 CPython 文档中，有几个常见的情况应该使用更简单的标记

• *arg*（呈现为 arg）用于函数和方法参数。

• ``True``/``False``/``None`` 用于 True/False/None。

此外，CPython 文档定义了一些自定义角色

• :cve:`YYYY-NNNNN`：链接到常见漏洞和暴露条目。

• :cwe:`NNN`：链接到常见弱点枚举条目。

• :gh:`ID`：链接到 GitHub 问题。

• :issue:`ID`：链接到 bugs.python.com 问题。

• :pypi:`NAME`：链接到 PyPI 上的项目。

• :source:`PATH`：链接到 GitHub 上的源文件。

还有一些其他功能可以使交叉引用角色更通用

• 您可以提供明确的标题和引用目标，就像在 reST 直接超链接中一样：:role:`title <target>` 将引用 target，但链接文本将是 title。

• 如果您在内容前加上 !，则不会创建引用/超链接。

• 对于 Python 对象角色，如果您在内容前加上 ~，则链接文本将仅是目标的最后一个组件。例如，:meth:`~Queue.Queue.get` 将引用 Queue.Queue.get，但仅显示 get 作为链接文本。

  在 HTML 输出中，链接的 title 属性（例如，在鼠标悬停时显示为工具提示）将始终是完整的目标名称。

• 不支持组合 ~ 和 !（例如，:meth:`~!Queue.Queue.get`）。您可以通过使用 ! 和目标的最后一个组件（例如，:meth:`!get`）来获得相同的结果。

以下角色引用模块中的对象，如果找到匹配的标识符，则可能超链接

mod

模块的名称；可以使用点分名称。这也应该用于包名称。

func

Python 函数的名称；可以使用带点的名称。角色文本不应包含尾随括号以提高可读性。在搜索标识符时会去掉括号。

data

模块级变量或常量的名称。

const

“已定义”常量的名称。这可能是 C 语言 #define 或不打算更改的 Python 变量。

class

类名；可以使用带点的名称。

meth

对象方法的名称。角色文本应包括类型名称和方法名称。可以使用带点的名称。

attr

对象的数据属性的名称。

exc

异常的名称。可以使用带点的名称。

此标记中包含的名称可以包括模块名称和/或类名称。例如，:func:`filter` 可以指当前模块中名为 filter 的函数，也可以指同名内置函数。相比之下，:func:`foo.filter` 明确指代 foo 模块中的 filter 函数。

通常，首先在不进一步限定的情况下搜索这些角色中的名称，然后加上当前模块名称，然后加上当前模块和类名称（如果有）。如果在名称前加上一个点，则此顺序将颠倒。例如，在 codecs 模块的文档中，:func:`open` 始终指内置函数，而 :func:`.open` 指 codecs.open()。

使用类似的启发式方法来确定名称是否是当前记录类的属性。

---

如果在 API 文档中定义了以下角色，它们将创建对 C 语言结构的交叉引用

c:data

C 语言变量的名称。

c:func

C 语言函数的名称。应包括尾随括号。

c:macro

如上所述，“简单”C 宏的名称。

c:type

C 语言类型的名称。

c:member

如上所述，C 类型成员的名称。

---

以下角色不引用对象，但可以创建交叉引用或内部链接

envvar

环境变量。生成索引条目。

keyword

Python 关键字的名称。使用此角色将生成指向关键字文档的链接。 True、False 和 None 不使用此角色，而是使用简单的代码标记（``True``），因为它们是语言的基础，任何程序员都应该知道它们。

option

Python 的命令行选项。必须包括前导连字符。如果存在匹配的 cmdoption 指令，则链接到它。对于其他程序或脚本的选项，请使用简单的 ``code`` 标记。

token

语法标记的名称（在参考手册中用于在制作显示之间创建链接）。

---

以下角色创建对术语表中术语的交叉引用

term

术语表中术语的引用。术语表使用 glossary 指令创建，其中包含带有术语和定义的定义列表。它不必与 term 标记在同一文件中，事实上，默认情况下，Python 文档在 glossary.rst 文件中有一个全局术语表。

如果你使用术语表中未解释的术语，则在构建期间会收到警告。

---

以下角色除了以不同的样式设置文本格式外，没有其他特殊功能

command

操作系统级命令的名称，例如 rm。

dfn

标记文本中术语的定义实例。（不生成索引条目。）

文件

文件或目录的名称。在内容中，可以使用大括号来表示“变量”部分，例如

``spam`` is installed in :file:`/usr/lib/python2.{x}/site-packages` ...

在构建的文档中，x 将以不同的方式显示，以表示它将被 Python 次要版本替换。

guilabel

作为交互式用户界面一部分显示的标签应使用 guilabel 标记。这包括文本界面中的标签，例如使用 curses 或其他基于文本的库创建的标签。界面中使用的任何标签都应使用此角色标记，包括按钮标签、窗口标题、字段名称、菜单和菜单选择名称，甚至选择列表中的值。

kbd

标记一系列击键。键序列的形式可能取决于平台或应用程序特定的约定。如果没有相关的约定，则应拼出修饰键的名称，以提高新用户和非母语人士的可访问性。例如，xemacs 键序列可以标记为 :kbd:`C-x C-f`，但如果不引用特定应用程序或平台，则应将同一序列标记为 :kbd:`Control-x Control-f`。

mailheader

RFC 822 样式邮件头的名称。此标记并不表示该头被用于电子邮件中，但可用于引用任何“样式”相同的头。这也用于由各种 MIME 规范定义的头。应以通常在实践中找到的方式输入头名称，在有多个常见用法的情况下，首选使用驼峰式命名约定。例如：:mailheader:`Content-Type`。

makevar

make 变量的名称。

manpage

对 Unix 手册页的引用，包括部分，例如 :manpage:`ls(1)`。

menuselection

应使用 menuselection 角色标记菜单选择。这用于标记完整的菜单选择序列，包括选择子菜单和选择特定操作，或此类序列的任何子序列。各个选择的名称应由 --> 分隔。

例如，要标记选择“开始 > 程序”，请使用此标记

:menuselection:`Start --> Programs`

在包含包含一些尾部指示符的选择时，例如某些操作系统用于指示命令打开对话框的省略号，应从选择名称中省略指示符。

mimetype

MIME 类型或 MIME 类型组件（主要或次要部分，单独使用）的名称。

newsgroup

Usenet 新闻组的名称。

program

可执行程序的名称。对于某些平台，这可能与可执行文件的名称不同。特别是，应省略 Windows 程序的 .exe（或其他）扩展名。

regexp

正则表达式。不应包含引号。

samp

一段文字文本，例如代码。在内容中，可以使用大括号来表示“变量”部分，如 :file:。

如果您不需要“变量部分”指示，请改用标准的 ``code``。

以下角色生成外部链接

pep

对 Python 增强提案的引用。这会生成适当的索引条目。生成文本“PEP number”；在 HTML 输出中，此文本是到指定 PEP 的在线副本的超链接。此类超链接不应替代在手册中正确记录语言。

rfc

对互联网请求评论的引用。这会生成适当的索引条目。生成文本“RFC number”；在 HTML 输出中，此文本是到指定 RFC 的在线副本的超链接。

请注意，没有特殊角色可以包含超链接，因为您可以使用标准 reST 标记来实现此目的。

交叉链接标记

为了支持对文档中任意部分的交叉引用，标准 reST 标签被“滥用”了一点：每个标签都必须位于节标题之前；并且每个标签名称在整个文档源中必须唯一。

然后，您可以使用 :ref:`label-name` 角色引用这些部分。

示例

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

:ref: 调用将替换为节标题。

或者，如果您提供链接文本 :ref:`link text <reference-label>`，则可以引用任何标签（不仅仅是节标题）。

段落级标记

这些指令创建短段落，可以在信息单元和普通文本中使用

note

用户在使用 note 所涉及的任何 API 位时应该了解的有关 API 的特别重要信息。指令的内容应以完整句子书写，并包括所有适当的标点符号。

示例

.. note::

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

warning

用户在使用 warning 所涉及的任何 API 位时应该了解的有关 API 的重要信息。指令的内容应以完整句子书写，并包括所有适当的标点符号。为了不吓跑用户远离充满警告的页面，此指令只应在涉及崩溃、数据丢失或安全影响的可能性时选择 note。

versionadded

此指令记录了 Python 的版本，该版本将所述特性或其中一部分添加到库或 C API 中。当这适用于整个模块时，它应放在模块部分的顶部，在任何散文之前。添加带有指令的新 API (class、attribute、function、method、c:type 等) 时，应在其描述块的末尾包含 versionadded。

必须给出第一个参数，即所讨论的版本。第二个参数是可选的，可用于描述该特性的详细信息。

示例

.. function:: func()

   Return foo and bar.

   .. versionadded:: 3.5

versionchanged

类似于 versionadded，但描述了命名特性何时以及在哪些方面发生了变化（新参数、更改的副作用、平台支持等）。此项必须具有第二个参数（更改说明）。

示例

.. function:: func(spam=False)

   Return foo and bar, optionally with *spam* applied.

   .. versionchanged:: 3.6
      Added the *spam* parameter.

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

deprecated

指示所述特性已弃用的版本。

有一个必需的参数：该特性已弃用的版本。

示例

.. deprecated:: 3.8

deprecated-removed

类似于 deprecated，但它还指示了该特性在哪个版本中被移除。

有两个必需的参数：该特性已弃用的版本，以及该特性被移除的版本。

示例

.. deprecated-removed:: 3.8 4.0

impl-detail

此指令用于标记特定于 CPython 的信息。将其与块内容或单个句子一起用作参数，即

.. impl-detail::

   This describes some implementation detail.

   More explanation.

或

.. impl-detail:: This shortly mentions an implementation detail.

“CPython 实现细节：”会自动添加到内容之前。

seealso

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

seealso 指令通常放置在任何子部分之前的部分中。对于 HTML 输出，它显示在文本的主流程中。

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

.. seealso::

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

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

rubric

此指令创建一个段落标题，不用于创建目录节点。它当前用于“脚注”标题。

居中

此指令创建一个居中的粗体段落。如下使用

.. centered::

   Paragraph contents.

目录标记

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

toctree

此指令在当前位置插入“TOC 树”，使用指令正文中给出的文件中的各个 TOC（包括“子 TOC 树”）。可以给定数字 maxdepth 选项以指示树的深度；默认情况下，包括所有级别。

考虑此示例（取自库参考索引）

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more files listed here)

这完成了以下两件事

• 从所有这些文件中插入目录，最大深度为 2，即一个嵌套标题。这些文件中的 toctree 指令也考虑在内。

• Sphinx 知道文件 intro、strings 等的相对顺序，并且知道它们是显示的文件（库索引）的子级。根据此信息，它生成“下一章”、“上一章”和“父章”链接。

最后，构建过程中包含的所有文件都必须出现在一个 toctree 指令中；如果 Sphinx 发现未包含的文件，它会发出警告，因为这意味着无法通过标准导航访问此文件。

源目录根目录中的特殊文件 contents.rst 是 TOC 树层次结构的“根”；“目录”页面由此生成。

生成索引的标记

如前所述，Sphinx 自动从所有信息单元（如函数、类或属性）创建索引条目。

但是，还有一个可用的显式指令，以使索引更全面，并在信息主要不包含在信息单元中的文档（例如语言参考）中启用索引条目。

指令为 index，包含一个或多个索引条目。每个条目由类型和值组成，用冒号分隔。

例如

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

此指令包含五个条目，这些条目将转换为生成索引中的条目，该索引链接到索引语句的确切位置（或者，对于离线媒体，链接到相应的页码）。

可能的条目类型为

single

创建单个索引条目。可以通过用分号分隔子条目文本使其成为子条目（此表示法也用于以下描述创建哪些条目）。

pair

pair: loop; statement 是一个快捷方式，可创建两个索引条目，即 loop; statement 和 statement; loop。

triple

同样，triple: module; search; path 是一个快捷方式，可创建三个索引条目，即 module; search path、search; path, module 和 path; module search。

module, keyword, operator, object, exception, statement, builtin

这些都创建两个索引条目。例如，module: hashlib 创建条目 module; hashlib 和 hashlib; module。内置条目类型略有不同，因为在创建两个条目时，使用“内置函数”代替“内置”。

对于仅包含“单一”条目的索引指令，有一个简写符号

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

这创建四个索引条目。

语法产生式显示

有特殊标记可用于显示形式语法的产生式。标记简单，并不试图对 BNF（或任何派生形式）的所有方面进行建模，但提供了足够的信息，以便以将符号的使用呈现为指向符号定义的超链接的方式显示上下文无关语法。有此指令

productionlist

此指令用于包围一组产生式。每个产生式都在单行上给出，并由冒号分隔，后面是定义。如果定义跨越多行，则每行续行都必须以与第一行相同列的冒号开头。

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

定义可以包含标记为解释文本的标记名称（例如 unaryneg ::= "-" `integer`）——这会生成到这些标记的产生式的交叉引用。

请注意，在产生式中不会执行进一步的 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`

替换

文档系统提供了默认定义的三个替换。它们在构建配置文件 conf.py 中设置。

|release|

替换为文档引用的 Python 版本。这是包括 alpha/beta/候选版本标记在内的完整版本字符串，例如 2.5.2b3。

|version|

替换为文档引用的 Python 版本。这仅包含主版本和次版本部分，例如 2.5，即使对于版本 2.5.1 也是如此。

|today|

替换为今天的日期或在构建配置文件中设置的日期。通常格式为 April 14, 2007。