指令

As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.

See 域 for roles added by domains.

参见

参考:ref: `reStructuredText 初级入门 <rst-directives>`获取Docutils提供的指令的概述。

目录

由于reST不具备将多个文档互连或将文档拆分为多个输出文件的功能，Sphinx使用一个自定义指令来添加构成文档的单个文件以及目录之间的关系。“toctree”指令是中心元素。

备注

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

备注

为当前文档创建目录(.rst文件)，使用标准reST 内容指令。

.. toctree::

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

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

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

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

这可以完成两件事：

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

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

条目

文档标题：rst:方向将自动从引用文档的标题中读取`toctree’。如果这不是您想要的，您可以使用与reST超链接类似的语法指定一个显式的标题和目标（以及Sphinx的：ref:cross-referencementsyntax 1）。这看起来像：

.. toctree::

   intro
   All about strings <strings>
   datatypes

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

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

章节编号

如果您想在HTML输出中包含节号，请给**toplevel**目录树一个“numbered`”选项。例如：：

.. toctree::
   :numbered:

   foo
   bar

然后从“foo”的标题开始编号。子目录树是自动编号的（不要给那些子目录树加上“编号”标志）。

通过将深度作为“numbered”的数字参数，也可以对特定深度进行编号。

额外选项

您可以使用“caption``选项来提供目录树标题，也可以使用``name``选项提供可以通过以下方式引用的隐式目标名称：rst:角色：`ref：

.. toctree::
   :caption: Table of Contents
   :name: mastertoc

   foo

如果只想显示树中文档的标题，而不显示同级别的其他标题，可以使用“titlesonly”选项：

.. toctree::
   :titlesonly:

   foo
   bar

您可以在toctree指令中使用“globbing”，方法是提供“glob”标志选项。然后将所有条目与可用文档列表进行匹配，并按字母顺序将匹配项插入到列表中。例子：：

.. toctree::
   :glob:

   intro*
   recipe/*
   *

这首先包括名称以“intro”开头的所有文档，然后是“recipe”文件夹中的所有文档，然后是所有剩余的文档（当然，除了包含指令的文档）_

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

您可以使用“reversed”标志选项来反转列表中条目的顺序。当使用“glob”标志选项反转文件顺序时，这很有用。例子：：

.. toctree::
   :glob:
   :reversed:

   recipe/*

您还可以为该指令提供一个“隐藏”选项，如下所示：

.. toctree::
   :hidden:

   doc_1
   doc_2

这仍然会通知Sphinx文档层次结构，但不会在指令所在的位置向文档中插入链接——如果您打算自己以不同的样式或在HTML侧边栏中插入这些链接，这是有意义的。

如果您希望只有一个顶级目录树并隐藏所有其他较低级别目录树，则可以将“includehidden”选项添加到顶层目录树条目中：

.. toctree::
   :includehidden:

   doc_1
   doc_2

所有其他的toctree条目可以通过“hidden”选项消除。

最后，：term:`source directory`（或子目录）中的所有文档都必须出现在某个“toctree”指令中；如果Sphinx发现未包含的文件，则会发出警告，因为这意味着无法通过标准导航访问该文件。

使用：confval:`exclude_patterns`显式地从生成中排除文档或目录。使用：ref:`the“orphan”metadata 1`来构建文档，但通知Sphinx不能通过toctree访问它。

The “root document” (selected by root_doc) is the “root” of the TOC tree hierarchy. It can be used as the documentation’s main page, or as a “full table of contents” if you don’t give a maxdepth option.

在 0.3 版本发生变更: 添加“globbing”选项。

在 0.6 版本发生变更: 添加了“编号”和“隐藏”选项以及外部链接和对“自我”引用的支持。

在 1.0 版本发生变更: 添加“titlesonly”选项。

在 1.1 版本发生变更: 在“numbered”中添加了数字参数。

在 1.2 版本发生变更: 增加了“includehidden”选项。

在 1.3 版本发生变更: 增加了“标题”和“名称”选项。

特殊的名称

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

特殊文件名（以及为其生成的页面）为：

  • genindex, modindex, search

    它们分别用于通用索引、Python模块索引和搜索页面。

    通用索引由来自模块的条目填充，所有索引生成：ref:object descriptions 1，以及来自：rst:方向：`index`指令。

    Python模块索引包含一个条目：rst:方向：`py:module`指令。

    搜索页面包含一个表单，该表单使用生成的JSON搜索索引和JavaScript对生成的文档进行全文搜索，以查找搜索词；它应该适用于支持现代JavaScript的所有主要浏览器。

  • 每个名字都以``_``开头

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

警告

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

  • 对于基于HTML的格式，不要使用冒号“：”。链接到其他部分可能不起作用。

  • 不要在ePub格式中使用加号“+”。可能找不到某些资源。

段落级标记

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

.. note::

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

例如：

.. note::

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

关于接口的重要信息，用户在使用与警告相关的任何接口位时都应该非常清楚。指令的内容应以完整的句子书写，并包括所有适当的标点符号。这不同于：rst:方向：`note`因为它的建议超过：rst:方向：`note`获取有关安全性的信息。

.. versionadded:: version

该指令记录了将所描述的特性添加到库或capi的项目的版本。当这适用于整个模块时，它应该放在模块部分的顶部，然后放在任何散文之前。

必须给出第一个参数，并且是有问题的版本；您可以添加第二个参数，其中包含对更改的*简要*解释。

例如：

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

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

.. versionchanged:: version

类似：rst:方向：versionadded，但描述了命名功能在某些方面发生了什么变化（新参数、更改的副作用等）。

.. deprecated:: version

类似：rst:方向：versionchanged，但描述该功能何时被弃用。也可以给出解释，例如告诉读者应该用什么代替。例子：：

.. deprecated:: 3.1
   Use :func:`spam` instead.
.. versionremoved:: version

Similar to versionadded, but describes when the feature was removed. An explanation may be provided to inform the reader what to use instead, or why the feature was removed. Example:

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

Added in version 7.3.

.. seealso::

许多部分包括对模块文档或外部文档的引用列表。这些列表是使用以下方法创建的：rst:方向：`seealso`指令。

这个：rst:方向：`seealso`指令通常放在节中任何子节之前。对于HTML输出，它显示在文本的主流之外。

内容包括：rst:方向：`seealso`指令应为reST定义列表。例子：：

.. seealso::

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

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

还有一个“短格式”可以这样写：

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

Added in version 0.5: 短格式。

.. rubric:: title

此指令创建一个段落标题，不用于创建目录节点。

备注

如果评估准则的*标题*是“脚注”（或所选语言的等价物），则LaTeX编写器将忽略此评估准则，因为它假定仅包含脚注定义，因此会创建一个空标题。

.. centered::

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

.. centered:: LICENSE AGREEMENT

自 1.1 版本弃用: This presentation-only directive is a legacy from older versions. Use a rst-class directive instead and add an appropriate style.

.. hlist::

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

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

.. hlist::
   :columns: 3

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

Added in version 0.6.

显示代码示例

There are multiple ways to show syntax-highlighted literal code blocks in Sphinx:

Doctest blocks can only be used to show interactive Python sessions, while the remaining three can be used for other languages. Of these three, literal blocks are useful when an entire document, or at least large sections of it, use code blocks with the same syntax and which should be styled in the same manner. On the other hand, the code-block directive makes more sense when you want more fine-tuned control over the styling of each block or when you have a document containing code blocks using multiple varied syntaxes. Finally, the literalinclude directive is useful for including entire code files in your documentation.

In all cases, Syntax highlighting is provided by Pygments. When using literal blocks, this is configured using any highlight directives in the source file. When a highlight directive is encountered, it is used until the next highlight directive is encountered. If there is no highlight directive in the file, the global highlighting language is used. This defaults to python but can be configured using the highlight_language config value. The following values are supported:

  • ``无```（不突出显示）

  • “默认”（类似于“python3”，但有一个回退到“none”，没有警告高亮显示失败；当:confval:高亮_语言 未设置时的默认值)

  • ``guess``（让Pygments根据内容猜测lexer，只适用于某些可识别的语言）

  • python

  • rest

  • c

  • … 以及其他Pygments支持的lexer别名`_

如果使用所选语言高亮显示失败（即Pygments发出“错误”标记），则块不会以任何方式高亮显示。

重要

支持的lexer别名列表被绑定到加长版本。如果您想确保一致的高亮显示，您应该修正您的Pygments版本。

.. highlight:: language

例如：

.. highlight:: c

在遇到下一个“高亮”指令之前，将使用此语言。如前所述，*语言*可以是Pygments支持的任何lexer别名。

选项

:linenothreshold: threshold (number (optional))

允许为代码块生成行号。

此选项接受一个可选数字作为阈值参数。如果给定任何阈值，指令将只为超过N行的代码块生成行号。如果没有给出，将为所有代码块生成行号。

例如：

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

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

Added in version 2.1.

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

例如：

.. code-block:: ruby

   Some Ruby code.

The directive’s alias name sourcecode works as well. This directive takes a language name as an argument. It can be any lexer alias supported by Pygments. If it is not given, the setting of highlight directive will be used. If not set, highlight_language will be used. To display a code example inline within other text, rather than as a separate block, you can use the code role instead.

在 2.0 版本发生变更: “语言”参数变成可选的。

选项

: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支持“强调线”选项。

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

In order to cross-reference a code-block using either the ref or the numref role, it is necessary that both name and caption be defined. The argument of name can then be given to numref to generate the cross-reference. Example:

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

When using ref, it is possible to generate a cross-reference with only name defined, provided an explicit title is given. Example:

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)

Strip indentation characters from the code block. When number given, leading N characters are removed. When no argument given, leading spaces are removed via textwrap.dedent(). For example:

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

       some ruby code

Added in version 1.3.

在 3.5 版本发生变更: Support automatic dedent.

:force: (no value)

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

Added in version 2.1.

.. literalinclude:: filename

通过将示例文本存储在只包含纯文本的外部文件中，可以包括更长的逐字文本显示。可以使用“literalnclude”指令包含该文件。 [#] _例如，要包含Python源文件：file：example.py，用途：

.. literalinclude:: example.py

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

额外选项

比如:rst:dir:code-block，指令支持“linenos”标签选项打开行号,这个“lineno-start”选项选择第一行号，这个“emphasize-lines”选择强调特定的行，“名”选项提供一个隐式的目标名称，“取消缩进”选项条缩进字符代码块，以及一个“语言”选项来选择一个语言不同于当前文件的标准语言。此外，支持“caption”选项；但是，可以在不带参数的情况下提供文件名作为标题。选项示例:

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

如果给“tab width”选项指定所需的制表符宽度，则输入中的制表符将展开。

假定Include文件编码在：confval: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 ”和“end-before”/“end-at”可以有相同的字符串。“start-after” / “start-at”过滤包含选项字符串的行之前的行(“start-at”将保持该行)。然后“end-before”/“end-at”过滤包含选项字符串的行之后的行(“end-at”将保留该行，“end-before”’跳过第一行)。

备注

如果你想像下面这样只选择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

Useful cases of these option is working with tag comments. :start-after: [initialize] and :end-before: [initialized] options keep lines between comments:

if __name__ == "__main__":
    # [initialize]
    app.start(":8000")
    # [initialized]

当以上述任何一种方式选择行时，“强调行”中的行号是指从“1”开始连续计数的选定行。

指定要显示的文件的特定部分时，显示原始行号可能很有用。这可以使用“lineno match”选项来完成，但是只有当所选内容包含连续的行时，才允许使用该选项。

您可以分别使用“prepend”和“append”选项在包含的代码前面加上和/或追加一行。这对于突出显示不包含“<”的PHP代码非常有用？php`/``？>``标记。

如果要显示代码的差异，可以通过提供“diff”选项指定旧文件：

.. literalinclude:: example.py
   :diff: example.py.orig

这显示了统一的diff格式的“example.py”与“example.py.orig”之间的差异。

“force”选项可以忽略高亮显示的小错误。

在 0.4.3 版本发生变更: 添加了“编码”选项

在 0.6 版本发生变更: 添加“pyobject”、“lines”、“start after”和“end before”选项以及对绝对文件名的支持。

在 1.0 版本发生变更: 添加“prepend”和“append”选项以及“tab width”。

在 1.3 版本发生变更: 添加了“diff”，“ lineno-match”，“标题”，“名称”，和“取消缩进”选项。

在 1.4 版本发生变更: Added the class option.

在 1.5 版本发生变更: 添加“start-at”和“end-at”选项。

在 1.6 版本发生变更: 当“start after”和“lines”同时使用时，根据“start after”的第一行被认为是“lines”的行号“1”。

在 2.1 版本发生变更: 添加了“force”选项

在 3.5 版本发生变更: Support automatic dedent.

术语表

.. glossary::

此指令必须包含reST定义列表，如带有术语和定义的标记。电缆定义如下：rst:角色：`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”没有被规范化；key“A”和“A”成为不同的组。使用“key”中的整个字符而不是第一个字符；它用于“组合字符序列”和“代理项对”分组键。

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

Added in version 0.6: 现在可以给glossary指令一个“sorted:`”标志，它将自动按字母顺序对条目进行排序。

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

在 1.4 版本发生变更: 术语表术语的索引键应该被认为是*实验性的*。

在 4.4 版本发生变更: In internationalized documentation, the :sorted: flag sorts according to translated terms.

元信息标记

.. sectionauthor:: name <email>

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

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

默认情况下，此标记不会以任何方式反映在输出中（这有助于跟踪贡献），但您可以将配置值confval:`showüu authors`设置为`True``以使它们在输出中生成段落。

.. codeauthor:: name <email>

这个：rst:方向作者：`author`可以出现多个代码，就像代码的作者：rst:方向：`sectionauthor`指定文档的作者。它也只在：confval:`show'u authors’配置值为“True”时生成输出。

索引生成标记

Sphinx automatically creates index entries from all object descriptions (like functions, classes or attributes) like discussed in 域.

但是，也可以使用显式标记，使索引更全面，并使索引条目能够在信息单元（如语言引用）中不主要包含在信息单元中的文档中。

.. index:: <entries>

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

例如：

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

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

...

此指令包含五个条目，这些条目将被转换为生成的索引中的条目，这些条目链接到索引语句的确切位置（或者，如果是脱机媒体，则是相应的页码）。

由于索引指令在源代码中的位置生成交叉引用目标，所以将它们*放在它们引用的对象之前是有意义的，例如，标题，如上面的示例所示。

可能的条目类型有：

单个的

Creates a single index entry. Can be made a sub-entry by separating the sub-entry text with a semicolon (this notation is also used below to describe what entries are created). Examples:

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

成对的

A shortcut to create two index entries. The pair of values must be separated by a semicolon. Example:

.. index:: pair: loop; statement

This would create two index entries; loop; statement and statement; loop.

三倍的

A shortcut to create three index entries. All three values must be separated by a semicolon. Example:

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

This would create three index entries; module; search path, search; path, module, and path; module search.

参阅

A shortcut to create an index entry that refers to another entry. Example:

.. index:: see: entry; other

This would create an index entry referring from entry to other (i.e. ‘entry’: See ‘other’).

另请参见

Like see, but inserts ‘see also’ instead of ‘see’.

模块，关键字，运算符，对象，异常，语句，内置

These deprecated shortcuts all create two index entries. For example, module: hashlib creates the entries module; hashlib and hashlib; module.

自 1.0 版本弃用: These Python-specific entry types are deprecated.

在 7.1 版本发生变更: Removal version set to Sphinx 9.0. Using these entry types will now emit warnings with the index category.

您可以用感叹号作为前缀来标记“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:

而：rst:方向：`index`指令是一个块级标记，链接到下一段的开头，还有一个相应的角色，它直接在使用它的位置设置链接目标。

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

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

Added in version 1.1.

包括基于标签的内容

.. only:: <expression>

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

.. only:: html and draft

Undefined tags are false, defined tags (via the -t command-line option or within conf.py, see here) are true. Boolean expressions, also using parentheses (like (latex or html) and draft) are supported.

当前生成器的*format*和*name*（html`、latex``或``text``）始终设置为标记[#]。为了明确区分格式和名称，还添加了前缀“format”和“builder”，例如epub builder定义了标记“html”、“epub”、“format”和“builder”。

这些标准标记是在读取配置文件之后设置的，因此它们在那里不可用。

所有标记都必须遵循“Identifiers and keywords”中规定的标准Python标识符语法<https://docs.python.org/3/reference/lexical_analysis.htmlidentifiers>`_文件。也就是说，标记表达式只能由符合Python变量语法的标记组成。在ASCII中，它由大小写字母“A”到“Z”、下划线“uu”和数字“0”到“9”组成，第一个字符除外。

Added in version 0.6.

在 1.2 版本发生变更: 添加了生成器的名称和前缀。

警告

本指令仅用于控制文件的内容。它不能控制分区、标签等。

表格

使用：ref:`reStructuredText tables 1’

  • 网格表语法（：duref:ref 1），

  • 简单表语法（：duref:`ref 1’），

  • ：dudir:`csv table`语法，

  • or :dudir:`list-table`语法，

dudir:`table`指令用作*grid*和*simple*语法的可选包装器。

They work fine in HTML output, but rendering tables to LaTeX is complex. Check the latex_table_style.

在 1.6 版本发生变更: Merged cells (multi-row, multi-column, both) from grid tables containing complex contents such as multiple paragraphs, blockquotes, lists, literal blocks, will render correctly to LaTeX output.

.. tabularcolumns:: column spec

This directive influences only the LaTeX output for the next table in source. The mandatory argument is a column specification (known as an “alignment preamble” in LaTeX idiom). Please refer to a LaTeX documentation, such as the wiki page, for basics of such a column specification.

Added in version 0.3.

备注

:rst:方向：tablerColumns`与table指令的:widths:``选项冲突。如果同时指定了这两个选项，`:widths:``选项将被忽略。

Sphinx will render tables with more than 30 rows with longtable. Besides the l, r, c and p{width} column specifiers, one can also use \X{a}{b} (new in version 1.5) which configures the column width to be a fraction a/b of the total line width and \Y{f} (new in version 1.6) where f is a decimal: for example \Y{0.2} means that the column will occupy 0.2 times the line width.

When this directive is used for a table with at most 30 rows, Sphinx will render it with tabulary. One can then use specific column types L (left), R (right), C (centered) and J (justified). They have the effect of a p{width} (i.e. each cell is a LaTeX \parbox) with the specified internal text alignment and an automatically computed width.

警告

  • Cells that contain list-like elements such as object descriptions, blockquotes or any kind of lists are not compatible with the LRCJ column types. The column type must then be some p{width} with an explicit width (or \X{a}{b} or \Y{f}).

  • Literal blocks do not work with tabulary at all. Sphinx will fall back to tabular or longtable environments and generate a suitable column specification.

In absence of the tabularcolumns directive, and for a table with at most 30 rows and no problematic cells as described in the above warning, Sphinx uses tabulary and the J column-type for every column.

在 1.6 版本发生变更: Formerly, the L column-type was used (text is flushed-left). To revert to this, include \newcolumntype{T}{L} in the LaTeX preamble, as in fact Sphinx uses T and sets it by default to be an alias of J.

提示

A frequent issue with tabulary is that columns with little contents appear to be “squeezed”. One can add to the LaTeX preamble for example \setlength{\tymin}{40pt} to ensure a minimal column width of 40pt, the tabulary default of 10pt being too small.

提示

To force usage of the LaTeX longtable environment pass longtable as a :class: option to table, csv-table, or list-table. Use rst-class for other tables.

数学

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

请记住，当您将数学标记放在**Python docstrings**read by:mod:autodoc中时<sphinx.ext.autodoc>，要么必须将所有反斜杠加倍，要么使用Python原始字符串（r“raw”`）。

.. math::

指示显示的数学（取整行为自己的数学）。

指令支持多个方程式，这些方程式应该用空行分隔：

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

此外，每个等式都是在一个“split”环境中设置的，这意味着您可以在一个等式中有多条对齐的直线，以“&amp;”对齐，并用“\”分隔：

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

有关详细信息，请参阅“AmSMath LaTeX包”的文档。

当数学只有一行文本时，它也可以作为一个指令参数：

.. math:: (a + b)^2 = a^2 + 2ab + b^2

通常情况下，方程式不编号。如果你想让你的方程式得到一个数字，使用“标签”选项。当给定时，它将为表达式选择一个内部标签，通过该标签可以交叉引用，并生成一个表达式编号。参见：rst:角色：`eq`为例。编号样式取决于输出格式。

还有一个选项“nowrap”，可以防止在数学环境中包装给定的数学。当你给出这个选项时，你必须确保数学设置正确。例如：：

.. math::
   :nowrap:

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

参见

Sphinx中HTML输出的数学支持

用HTML生成器呈现数学选项。

latex_engine

说明如何配置LaTeX builder以在数学标记中支持Unicode文本。

语法生成显示

特殊标记可用于显示形式语法的结果。标记很简单，并不试图对BNF的所有方面（或任何派生形式）进行建模，但提供了足够的内容，允许上下文无关的语法以某种方式显示，从而使符号的使用呈现为符号定义的超链接。有这样的指令：

.. productionlist:: [productionGroup]

This directive is used to enclose a group of productions. Each production is given on a single line and consists of a name, separated by a colon from the following definition. If the definition spans multiple lines, each continuation line must begin with a colon placed at the same column as in the first line. Blank lines are not allowed within productionlist directive arguments.

The definition can contain token names which are marked as interpreted text (e.g., “sum ::= `integer` "+" `integer`”) – this generates cross-references to the productions of these tokens. Outside of the production list, you can reference to token productions using token.

:rst:dir:`productionlist`的*productionGroup*参数用于区分属于不同语法的不同的生产列表集。具有相同*productionGroup*的多个生产列表在相同范围内定义规则。

Inside of the production list, tokens implicitly refer to productions from the current group. You can refer to the production of another grammar by prefixing the token with its group name and a colon, e.g, “otherGroup:sum”. If the group of the token should not be shown in the production, it can be prefixed by a tilde, e.g., “~otherGroup:sum”. To refer to a production from an unnamed grammar, the token should be prefixed by a colon, e.g., “:sum”.

Outside of the production list, if you have given a productionGroup argument you must prefix the token name in the cross-reference with the group name and a colon, e.g., “myGroup:sum” instead of just “sum”. If the group should not be shown in the title of the link either an explicit title can be given (e.g., “myTitle <myGroup:sum>”), or the target can be prefixed with a tilde (e.g., “~myGroup:sum”).

请注意，在生产环境中不再执行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`

脚注