指令

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

查看 域 以获取域添加的角色.

参见

参见 reStructuredText 入门 以获取 Docutils 提供的指令概述.

内容目录

由于reStructuredText没有将多个文档互相连接或将文档拆分为多个输出文件的功能,Sphinx使用自定义指令在构成文档的单个文件之间添加关系,以及生成目录. toctree 指令是核心元素.

备注

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

备注

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

.. toctree::

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

每种输出格式中 “TOC 树” 的表示方式有所不同.输出多个文件的构建器（如 HTML）将其视为一个超链接集合.另一方面,输出单个文件的构建器（如 LaTeX、手册页等）则用 TOC 树上的文档内容替代它.

考虑以下示例（取自Python文档的库参考索引）:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

这完成了两件事:

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

  • Sphinx 知道文档 “intro”、”strings” 等的相对顺序,并且知道它们是所展示文档（库索引）的子文档.基于这些信息,它生成了 “下一章”、”上一章” 和 “父章” 链接.

条目

在 :rst :dir:`toctree` 中的文档标题将自动从引用文档的标题读取.如果这不是你想要的,你可以使用与 reStructuredText 超链接相似的语法（及 Sphinx 的 交叉引用语法 ）来指定一个明确的标题和目标.这看起来像这样:

.. toctree::

   intro
   All about strings <strings>
   datatypes

上面的第二行将链接到 strings 文档,但将使用 “关于字符串的一切” 作为标题,而不是 strings 文档的标题.

您也可以通过提供HTTP网址而不是文档名称来添加外部链接.

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

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

使用 exclude_patterns 显式排除文档或目录的完全构建. 使用 “孤立”元数据 让文档得以构建,但通知 Sphinx 它无法通过 toctree 访问.

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

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

选项

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

分配 类属性 .这是一个 :dudir :常见选项 <common-options> .例如:

.. toctree::
   :class: custom-toc

Added in version 7.4.

:name: label (text)

一个可以通过 :rst :role:`ref` 进行引用的隐式目标名称.这是一个 常见选项 .例如:

.. 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输出中也显示章节编号,请在*顶级* toctree中添加 `` :numbered:`` 选项.例如:

.. toctree::
   :numbered:

   foo
   bar

章节编号从 foo 的标题开始.子树会自动编号（不要给它们添加 numbered 标志）.

通过将深度作为数字参数传递给 numbered ,也可以对特定深度进行编号.

Added in version 0.6.

在 1.1 版本发生变更: 添加了数字 depth 参数.

:titlesonly:

只列出文档标题,而不是同级别的其他标题.例如:

.. toctree::
   :titlesonly:

   foo
   bar

Added in version 1.0.

:glob:

在 toctree 条目中解析 glob 通配符.所有条目都与可用文档的列表进行匹配,并将匹配项按字母顺序插入列表.例如:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

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

Added in version 0.3.

:reversed:

反转列表中条目的顺序.这在使用 :glob: 选项时特别有用.

Added in version 1.5.

:hidden:

一个隐藏的toctree仅仅定义了文档层次结构.它不会在指令的位置插入链接.

这在你有其它导航方式时是有意义的,例如通过手动链接、HTML侧边栏导航,或者如果你在顶层的toctree上使用 :includehidden: 选项.

Added in version 0.6.

:includehidden:

如果您希望有一个全局目录显示完整的文档结构,可以在*顶级* toctree 指令中添加 :includehidden: 选项.然后可以用 :hidden: 选项使子页面上的所有其他 toctree 隐藏.带有 :includehidden: 的顶级 toctree 将包含它们的条目.

Added in version 1.2.

特殊名称

Sphinx保留了一些文档名称供其自身使用;您不应该尝试创建这些名称的文档——这会造成问题.

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

  • genindex

    这是用于一般索引,其中填充了来自 index 指令和所有生成索引的 对象描述 的条目.例如,请参见 Sphinx 的 索引 .

  • modindex

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

  • search

    这是用于搜索页面的,包含一个表单,该表单使用生成的 JSON 搜索索引和 JavaScript 对生成的文档进行全文搜索关键字;它在所有主要浏览器上都能正常工作.例如,请参见 Sphinx 的 搜索页面 .

  • 每个以 _ 开头的名称

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

警告

请注意文件名中的特殊字符.某些格式可能会以意想不到的方式解释这些字符:

  • 在基于HTML的格式中,请不要使用冒号 : .链接到其他部分可能无法正常工作.

  • 请勿在ePub格式中使用加号 + .某些资源可能无法找到.

段落级标记

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

警告、信息和提示

警告指令创建了”警告”元素,这是一个标准化的系统,用于传达不同类型的信息,从有用的 提示 到至关重要的 危险 .这些指令可以在任何普通主体元素可以使用的地方使用,并且可以包含任意主体元素.共有九个具体命名的警告和通用 警告 指令.

.. attention::

需要读者注意的信息.指令的内容应使用完整的句子书写,并包含所有适当的标点符号.

示例:

注意

请注意.

.. caution::

信息,读者需谨慎对待.指令的内容应以完整的句子书写,并包括所有适当的标点符号.

示例:

小心

谨慎行事.

.. danger::

可能导致近期和当前危险的信息.如果不引起注意,可能会造成危险.指令的内容应以完整的句子编写,并包括所有适当的标点符号.

示例:

危险

让任何人不要认为可以逃避危险,因为爱终究会成为他自己的复仇者.

.. error::

与某些描述的失效模式相关的信息.指令的内容应以完整句子书写,并包含所有适当的标点符号.

示例:

错误

ERROR 418: 我是一把茶壶.

.. hint::

读者有用的信息.指令的内容应使用完整句子写成,并包括所有适当的标点符号.

示例:

提示

看花盆下面.

.. important::

重要信息,读者必须注意.指令的内容应以完整的句子撰写并包含所有适当的标点符号.

示例:

重要

这是一项至关重要的声明.

.. note::

一个特别重要的信息点,读者应当知道.指令的内容应以完整的句子书写,并包含所有适当的标点.

示例:

备注

此函数不适合发送罐装垃圾邮件.

.. tip::

一些对读者有用的小信息.指令的内容应以完整的句子书写,并包含所有适当的标点符号.

示例:

小技巧

记得涂防晒霜!

.. warning::

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

示例:

警告

警惕狗.

.. admonition:: title

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

示例:

这是一个标题

这是警告的内容.

.. seealso::

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

The seealso directive is typically placed in a section just before any subsections. The content of the seealso directive should be either a single line or a 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

Documentation of the zipfile standard module.

GNU tar manual, Basic Tar Format

tar归档文件的文档,包括GNU tar扩展.

描述版本之间的变化

.. versionadded:: version [brief explanation]

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

第一个参数必须给出,并且是相关的版本;您可以添加第二个参数,包含对更改的*简要*说明.

注意

指令头和解释之间不得有空行;这是为了使这些块在标记中视觉上连续.

示例:

.. 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 ,但描述该功能何时被弃用.也可以给出*简要*说明,例如告诉读者应该使用什么替代品.

示例:

.. 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: The spam() function is more flexible, and should be used instead.

演示

.. rubric:: title

一个标头类似于一个非正式标题,不对应于文档的结构,即它不会生成目录节点.

备注

如果该纲要的 标题 是 “脚注”（或所选语言的对应词）,则该纲要将被 LaTeX 写入程序忽略,因为它被认为只包含脚注定义,因此会导致创建空标题.

选项

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

分配 类属性 .这是一个 常见选项 .

:name: label (text)

一个可以通过 ref 引用的隐式目标名称.这是一个 常用选项 .

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

Added in version 7.4.1.

使用此选项指定标题的级别.在这种情况下,标题将会渲染为 HTML 输出中的 <h1> 到 <h6> ,或者在 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会话,而剩下的三个可以用于其他语言.在这三个中,literal块在整个文档中,或者至少大部分内容都使用相同语法的代码块并且应以相同方式样式化时非常有用.另一方面,:rst:dir:code-block 指令在您希望对每个块的样式进行更精细的控制,或者在您有一个包含多种不同语法的代码块的文档时更加有意义.最后,:rst:dir:literalinclude 指令可以用于将整个代码文件包含在文档中.

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

  • none (no highlighting)

  • default (similar to python3 but with a fallback to none without warning highlighting fails; the default when highlight_language isn’t set)

  • guess (let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)

  • python

  • rest

  • c

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

如果使用所选语言高亮失败（即 Pygments 发出 “错误” 令牌）,该块将不会以任何方式高亮.

重要

支持的词法分析器别名列表与Pygments版本相关.如果您想确保一致的高亮效果,您应该固定Pygments的版本.

.. 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 也有效.此指令接受一个语言名称作为参数.可以是 Pygments 支持的任何词法分析器别名 .如果没有给出,将使用 highlight 指令的设置.如果未设置,将使用 highlight_language .要在其他文本中 内联 显示代码示例,而不是作为单独的块,可以使用 code 角色.

在 2.0 版本发生变更: The language argument becomes optional.

选项

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

:caption: caption of code block (text)

为代码块设置一个标题.

Added in version 1.3.

:name: a label for hyperlink (text)

定义可以通过 :rst :role:`ref` 引用的隐式目标名称.例如:

.. code-block:: python
   :caption: this.py
   :name: this-py

   print('Explicit is better than implicit.')

为了使用 :rst :role:`ref` 或 numref 角色进行交叉引用,必须定义 name 和 caption .然后可以将 name 的参数传递给 numref 以生成交叉引用.示例:

See :numref:`this-py` for an example.

使用 :rst :role:`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)

图形的类名.

Added in version 1.4.

:dedent: number (number or no value)

从代码块中去除缩进字符.当给定数字时,删除前面的 N 个字符.当没有给定参数时,通过 :func :textwrap.dedent() 删除前导空格.例如:

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

       some ruby code

Added in version 1.3.

在 3.5 版本发生变更: 支持自动去缩进.

:force: (no value)

如果提供,将忽略高亮中的小错误.

Added in version 2.1.

.. literalinclude:: filename

可以通过将示例文本存储在一个只包含纯文本的外部文件中,来包含较长的逐字文本显示.该文件可以使用 literalinclude 指令包含.[#]_ 例如,要包含 Python 源文件 :file :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 and end-before/end-at can have same string. start-after/start-at filter lines before the line that contains option string (start-at will keep the line). Then end-before/end-at filter lines after the line that contains option string (end-at will keep the line and end-before skip the first line).

备注

如果您只想选择 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.

(当词汇表排序时,第一个术语决定排序顺序.)

如果您想为一般索引条目指定 “分组键”,可以将 “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:

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

Added in version 0.6.

在 4.4 版本发生变更: 在国际化文档中,按翻译术语进行排序.

元信息标记

.. sectionauthor:: name <email>

识别当前节的作者.参数应包括作者的姓名,以便用于展示和电子邮件地址.地址的域名部分应为小写.例如:

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

默认情况下,这种标记不会在输出中反映出来（它有助于跟踪贡献）,但您可以将配置值 show_authors 设置为 True ,以使它们在输出中生成一段文字.

.. codeauthor:: name <email>

The codeauthor directive, which can appear multiple times, names the authors of the described code, just like sectionauthor names the author(s) of a piece of documentation. It too only produces output if the show_authors configuration value is True.

索引生成标记

Sphinx会自动从所有对象描述（如函数、类或属性）中创建索引条目,如在 域 中讨论的.

然而,还有明确的标记可用,以使索引更加全面,并在信息主要不包含在信息单元中的文档中启用索引条目,例如语言参考.

.. index:: <entries>

这个指令包含一个或多个索引条目.每个条目由一个类型和一个值组成,以冒号分隔.

例如:

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

The execution context
---------------------

...

该指令包含五个条目,这些条目将在生成的索引中转换为条目,链接到索引语句的确切位置（或在离线媒体的情况下,相应的页码）.

由于索引指令在其源位置生成交叉引用目标,因此将它们放在所引用内容的*之前*是有意义的——例如,如上例中的标题.

可能的条目类型有:

单个

创建一个单一的索引条目.可以通过用分号分隔子条目文本将其作为子条目（此表示法也用于下面描述所创建的条目）.示例:

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

  • single: execution creates an index entry labelled execution.

  • single: execution; context creates an sub-entry of execution labelled context.

pair

创建两个索引条目的快捷方式.值对必须用分号分隔.例如:

.. index:: pair: loop; statement

这将创建两个索引条目: loop; statement 和 statement; loop .

triple

创建三个索引条目的快捷方式.所有三个值必须用分号分隔.示例:

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

这将创建三个索引条目; 模块;搜索路径 , 搜索;路径,模块 ,和 路径;模块搜索 .

见

创建一个引用其他条目的索引项的快捷方式.示例:

.. index:: see: entry; other

这将创建一个索引条目,从 entry 引用到 other （即 ‘entry’: 见 ‘other’）.

另见

类似于 see ,但插入的内容是 ‘see also’ 而不是 ‘see’.

模块, 关键字, 操作符, 对象, 异常, 语句, 内建

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

自 1.0 版本弃用: 这些特定于Python的入口类型已被弃用.

在 7.1 版本发生变更: 移除版本设置为 Sphinx 9.0.使用这些条目类型将会发出属于 index 分类的警告.

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

.. index:: Python

并且一页包含:

.. index:: ! Python

那么,指向后者页面的反向链接在这三个反向链接中被强调.

对于仅包含”单个”条目的索引指令,有一种简写法:

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

这将创建四个索引条目.

在 1.1 版本发生变更: 添加了 see 和 seealso 类型,以及标记主条目.

选项

:name: a label for hyperlink (text)

定义可以通过 :rst :role:`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 中定义,详见 这里 ）.支持布尔表达式（例如 (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 .

Added in version 0.6.

在 1.2 版本发生变更: 添加了构建器的名称和前缀.

警告

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

表格

使用 reStructuredText 表格 ,即使用任一

The table directive serves as optional wrapper of the grid and simple syntaxes.

它们在HTML输出中运行良好,但将表格渲染为LaTeX是复杂的.请检查 latex_table_style .

在 1.6 版本发生变更: 合并的单元格（多行、多列、两者都有）从包含复杂内容的网格表中,如多个段落、引用块、列表、文字块,将正确渲染为 LaTeX 输出.

.. tabularcolumns:: column spec

此指令仅影响源代码中下一个表格的LaTeX输出. 必填参数是列规格（在LaTeX术语中称为”对齐前言”）. 有关此类列规格的基础知识,请参考LaTeX文档,例如 wiki 页面 .

Added in version 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} （即每个单元格都是一个LaTeX \parbox ）,具有指定的内部文本对齐方式和自动计算的 width .

警告

  • 包含列表类型元素（例如对象描述、引用或任何类型的列表）的单元格与 LRCJ 列类型不兼容.因此,列类型必须是某种 p{宽度} ,并且需要明确的 宽度 （或 \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: class names (a list of class names, separated by spaces)

分配 类属性 .这是一个 常见选项 .

:name: label (text)

一个可以通过 ref 引用的隐式目标名称.这是一个 常用选项 .

:label: label (text)

通常,方程是没有编号的.如果您希望您的方程有编号,请使用 label 选项.提供该选项时,它会为方程选择一个内部标签,以便进行交叉引用,并生成方程编号.有关示例,请参见 eq .编号样式取决于输出格式.

:nowrap:

防止在数学环境中换行给定的数学表达式.当你使用这个选项时,必须确保数学表达式设置正确.例如:

.. math::
   :nowrap:

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

参见

数学支持

使用 HTML 构建器的数学呈现选项.

latex_engine

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

语法生成显示

特殊标记可用于展示形式文法的产生式.该标记简单,不试图建模 BNF（或任何派生形式）的所有方面,但提供了足够的信息,使上下文无关文法能够以一种方式展示,使符号的使用被渲染为超链接,指向符号的定义. 有这个指令:

.. productionlist:: [productionGroup]

该指令用于封闭一组生产.每个生产在一行中给出,包括一个名称,后面跟着一个冒号和定义.如果定义跨越多行,则每个续行必须以冒号开头,并与第一行的相同列对齐.在 productionlist 指令参数中不允许出现空行.

定义可以包含标记为解释文本的令牌名称（例如,”sum ::= `integer` "+`integer`”）– 这将生成对这些令牌的生成式的交叉引用.在生产列表之外,您可以使用 token 引用令牌生成.

productionGroup 参数用于 productionlist ,用于区分属于不同语法的不同类型的生成列表.因此,具有相同 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`

脚注