指令

正如之前讨论的，指令是一个通用的显式标记块。虽然 Docutils 提供了一些指令，但 Sphinx 提供了更多的指令，并使用指令作为主要的插件机制之一。

请参阅 域 了解域添加的角色。

参见

有关 Docutils 提供的指令的概述，请参阅 reStructuredText 入门。

目录

由于 reST 没有设施将几个文件相互连接，或将文件分割成多个输出文件，Sphinx 使用一个自定义指令来添加文件所组成的单个文件之间的关系，以及目录。toctree 指令是核心元素。

备注

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

备注

要为当前文件（.rst文件）创建目录，请使用标准的 reST contents 指令。

.. toctree::

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

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

考虑这个例子（取自 Python docs 的库引用索引）

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

这完成了两件事：

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

• Sphinx 知道文档 intro，strings 等的相对顺序，并且它知道它们是所显示文档的子项，即库索引。根据这些信息，它会生成 “next chapter”，“previous chapter” 和 “parent chapter” 链接。

栏目简介

第一个 toctree 中的文档标题将自动从引用文档的标题中读取。如果这不是您想要的，您可以使用与 reST 超链接类似的语法指定显式标题和目标（和 Sphinx 的 交叉引用语法）。这看起来像

.. toctree::

   intro
   All about strings <strings>
   datatypes

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

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

章节编号

如果你想在 HTML 输出中有节号，请给 顶层 toctree 一个 numbered 选项。例如

.. toctree::
   :numbered:

   foo
   bar

编号然后从 foo 的标题开始。子 toctrees 是自动编号的（不要给那些 numbered 标志）。

通过将深度作为 numbered 的数字参数，也可以编号到特定深度。

其他选项

你可以使用 caption 选项提供一个 toctree 标题，你可以使用 name 选项来提供可以通过使用引用的隐式目标名 ref

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

   foo

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

.. toctree::
   :titlesonly:

   foo
   bar

你可以在 toctree 指令中使用 “globbing”，给出 glob 标志选项。然后将所有条目与可用文档列表进行匹配，并按字母顺序将匹配项插入到列表中。例:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

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

特殊条目名称 self 代表包含toctree指令的文档。如果要从 toctree 生成”站点地图”，这非常有用。

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

.. toctree::
   :glob:
   :reversed:

   recipe/*

你也可以给指令一个 hidden 选项，比如

.. toctree::
   :hidden:

   doc_1
   doc_2

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

如果您只想拥有一个顶级 toctree 并隐藏所有其他较低级别的 toctree，则可以将 includehidden 选项添加到顶级 toctree 条目

.. toctree::
   :includehidden:

   doc_1
   doc_2

然后可以通过 hidden 选项消除所有其他 toctree 条目。

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

使用 exclude_patterns 可以完全排除文档或目录。使用 “orphan” 元数据 来构建文档，但通知 Sphinx 它是无法通过 toctree 访问的。

“根文件” （由 root_doc 选择）是 TOC 树层次结构的 “root”。如果你没有给出 maxdepth 选项，它可以用作文档的主页面，也可以用作 “完整的目录”。

在 0.3 版更改: 添加了 “globbing” 选项。

在 0.6 版更改: 添加了 “numbered” 和 “hidden” 选项以及外部链接和对 “self” 引用的支持。

在 1.0 版更改: Added “titlesonly” option.

在 1.1 版更改: 在 “numbered” 中添加了数字参数。

在 1.2 版更改: 添加了 “includehidden” 选项。

在 1.3 版更改: 添加了 “caption” 和 “name” 选项。

特别的名字

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

特殊文档名称（以及为它们生成的页面）是：

• genindex, modindex, search

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

  通用索引用模块中的项填充，所有索引生成 object descriptions，以及来自 index 指令。

  Python 模块索引包含一个条目 py:module 指令。

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

• 以 _ 开头的每个名字

  虽然 Sphinx 目前只使用了很少这样的名称，但您不应该创建包含此类名称的文档或包含文档的目录。（使用 _ 作为自定义模板目录的前缀是可以的。）

警告

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

• 对于基于 HTML 的格式，不要使用冒号 :。与其他部分的链接可能无效。

• 不要使用加号 + 作为 ePub 格式。可能找不到某些资源。

段落级标记

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

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

类似于 versionadded，但以某种方式描述命名特征中的更改时间和内容（新参数，更改的副作用等）。

.. 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 新版功能: The short form.

.. rubric:: title

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

备注

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

.. centered::

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

.. centered:: LICENSE AGREEMENT

1.1 版后已移除: 此演示文稿指令是旧版本的遗留代码。使用 rst-class 指令代替并添加适当的样式。

.. hlist::

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

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

.. hlist::
   :columns: 3

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

0.6 新版功能.

显示代码示例

有多种方法可以在 Sphinx 中显示语法高亮的文字代码块：

• 使用 reST doctest 块

• 使用 reST literal blocks，可选择与 highlight 指令结合使用；

• 使用 code-block 指令

• 并使用 literalinclude 指令。

Doctest 块只能用于显示交互式 Python 会话，而其余三个可用于其他语言。在这三个文件中，当整个文档或至少大部分文档使用具有相同语法的代码块并且应该以相同的方式设置样式时，文字块是有用的。另一方面，当你想要对每个块的样式进行更精细的控制，或者当你有一个包含使用多种不同语法的代码块的文档时，第一个 code-block 指令更有意义。最后，literalinclude 指令对于在文档中包含整个代码文件非常有用。

在所有情况下，语法高亮由 Pygments 提供。使用文字块时，使用源文件中的任何 [highlight 指令进行配置。当遇到 highlight 指令时，它会被使用，直到遇到下一个 highlight 指令。如果文件中没有 highlight 指令，则使用全局突出显示语言。这默认为 python，但可以使用 highlight_language 配置值进行配置。支持以下值：

• none （没有突出显示）

• default （类似于 python3 但是回退到 none 没有警告突出显示失败；默认情况下 highlight_language 未设置）

• guess （让 Pygments 根据内容猜测词法分析器，只适用于某些识别良好的语言)）

• python

• rest

• c

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

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

重要

支持的词法分类别名列表与 Pygment 版本相关联。如果要确保一致突出显示，则应修复 Pygments 的版本。

.. highlight:: language

例如

.. highlight:: c

这个语言会一直使用到遇到下一个 highlight 指令。如前所述，language 可以是 Pygments 支持的任何词法别名。

选项

:linenothreshold: threshold (number (optional))

启用为代码块生成行号。

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

例如

.. highlight:: python
   :linenothreshold: 5

:force: (no value)

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

2.1 新版功能.

.. code-block:: [language]

例如

.. code-block:: ruby

   Some Ruby code.

该指令的别名 sourcecode 也可以。该指令将语言名称作为参数。它可以是 Pygments 支持的任何词法分析别名 。如果没有给出，将使用 highlight 指令的设置。如果没有设置，将使用 highlight_language。

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

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

1.1 新版功能.

在 1.6.6 版更改: LaTeX 支持 emphasize-lines 选项。

:caption: caption of code block (text)

为代码块设置一个标题。

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.

1.3 新版功能.

:dedent: number (number or no value)

从代码块中剥离缩进字符。当给出数字时，前面的 N 个字符被删除。当没有给出参数时，通过 textwrap.dedent() 删除前面的空格。例如

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

       some ruby code

1.3 新版功能.

在 3.5 版更改: 支持自动缩进。

:force: (no value)

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

2.1 新版功能.

.. literalinclude:: filename

较长的逐字文本显示可以通过将示例文本存储在一个只包含纯文本的外部文件中来包含。该文件可以使用 literalinclude 指令来包含。3 例如，要包括 Python 源文件 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 和 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

这些选项的有用情况是与标记注释一起工作。:start-after: [initialized] 和 :end-before: [initialized] 选项在注释之间保留行数：

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

当以上述任何一种方式选择行时，emphasize-lines 中的行号是指这些被选中的行，从 1 开始连续计算。

当指定要显示文件的特定部分时，显示原始行号可能是有用的。这可以通过 lineno-match 选项来实现，但只有当选择由连续的行组成时才允许。

你可以分别使用 prepend 和 append 选项，在包含的代码中预置和/或附加一行。例如，这对突出显示不包括 <?php/?> 标记的 PHP 代码很有用。

如果你想显示代码的差异，你可以通过给一个 diff 选项来指定旧文件

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

这显示了 example.py 和 example.py.orig 之间的差异，统一的 diff 格式。

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.5 版更改: 添加了 start-at 和 end-at 选项。

在 1.6 版更改: 使用 start-after 和 lines 时，第一行按照 start-after 被认为是 lines 的行号 1 。

在 2.1 版更改: 添加 force 选项。

在 3.5 版更改: 支持自动缩进。

术语

.. glossary::

该指令必须包含带有术语和定义的 reST 定义列表标记。然后，这些定义可以引用 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.

（当词汇表被排序时，第一个术语决定了排序顺序。）

如果你想为一般的索引条目指定 “分组键”，你可以把一个 “key” 作为 “term : key”。例如

.. glossary::

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

注意 “key” 是用来分组键的，就像现在一样。“key”没有被规范化，键 “A” 和 “a” 成为不同的组。“key” 中的整个字符被用来代替第一个字符；它被用于 “合并字符序列” 和 “代理配对” 分组键。

在 i18n 的情况下，你可以指定 “localized term : key” 即使原文只有 “term” 部分。在这种情况下，翻译的 “localized term” 将被归入 “key” 组。

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>

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

.. codeauthor:: name <email>

codeauthor 指令，可以多次出现，命名所描述代码的作者，就像 sectionauthor 命名一篇文档的作者。如果 show_authors 配置值为 True，它也只产生输出。

索引生成标记

Sphinx 自动从所有对象描述（如函数，类或属性）创建索引条目,如 域 中所述。

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

.. index:: <entries>

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

例如

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

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

...

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

由于 index 指令在它们在源文件中的位置产生交叉引用的目标，所以把它们放在它们所指的东西之前是有意义的–例如标题，如上面的例子。

可能的条目类型是：

single

创建单个索引条目。可以通过用分号分隔子条目文本来创建子条目（下面也使用此符号来描述创建的条目）。

pair

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

triple

同样，triple: module; search; path 是一个创建三个索引条目的快捷方式，它们是 module; search path，search; path，module 和 path; module search。

see

see: entry; other 创建一个索引条目，从 entry 引用到 other。

seealso

就像 see，但是插入 “see also” 而不是 “see”。

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

这些都创建了两个索引条目。例如，module:hashlib 创建条目 module; hashlib 和 hashlib; module 。（这些是特定于 Python 的，因此已弃用。）

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

.. index:: Python

和一页包含

.. index:: ! Python

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

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

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

这将创建四个索引条目。

在 1.1 版更改: 添加了 see 和 seealso 类型，以及标记主条目。

选项

:name: a label for hyperlink (text)

定义隐含的目标名称，可以通过使用 ref 进行引用。例如

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

3.0 新版功能.

:index:

虽然 index 指令是一个块级标记，并链接到下一段的开头，但也有一个相应的角色，直接在使用它的地方设置链接 target。

角色的内容可以是一个简单的短语，然后保留在文本中并作为索引条目使用。它也可以是文本和 index 条目的组合，风格像有明确的交叉引用的目标。 在这种情况下，“target” 部分可以是一个完整的条目，就像上面描述的上面的指令。例如

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

1.1 新版功能.

包含基于标记的内容

.. only:: <expression>

只有当 表达式 为真时，才包括指令的内容。 表达式应该由标记组成，像这样

.. only:: html and draft

未定义的标记是 false，定义的标记（通过 -t 命令行选项或在 conf.py 内，见 这里 ）是真的。支持布尔表达式，也使用圆括号（如 html 和（latex 或 draft））。

当前构建器的 format 和 name （html, latex 或 text）总是被设置为标记 4。为了明确区分格式和名称，它们还被添加了前缀 format_ 和 builder_，例如，epub 构建器定义了标记 html、 epub、 format_html 和 builder_epub。

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

所有的标记必须遵循标准的 Python 标识符语法，如 标识符和关键字 文档中规定的。也就是说，一个标记表达式只能由符合 Python 变量语法的标记组成。在 ASCII 中，这包括大写和小写字母 A 到 Z，下划线 _，以及除第一个字符外的数字 0 到 9。

0.6 新版功能.

在 1.2 版更改: 添加了构建器的名字和前缀。

警告

该指令旨在仅控制文件的内容。它不能控制章节、标签等。

表格

使用 reStructuredText tables，即要么是

• grid 表语法（ref），

• 简单表的语法（ref），

• csv-table 语法

• 或者 list-table 语法

table 指令作为 grid 和 simple 语法的可选包装。

它们在 HTML 输出中运行良好，然而在 LaTeX 中使用表格时有一些麻烦：列宽很难自动正确确定。由于这个原因，存在以下指令：

.. tabularcolumns:: column spec

这个指令为源文件中出现的下一个表提供了一个 “column spec”。spec 是 LaTeX tabulary 包环境的第二个参数（Sphinx 用它来翻译表格）。它的值可以是:

|l|l|l|

which means three left-adjusted, nonbreaking columns. For columns with longer text that should automatically be broken, use either the standard p{width} construct, or tabulary’s automatic specifiers:

L	flush left column with automatic width
R	flush right column with automatic width
C	centered column with automatic width
J	justified column with automatic width

The automatic widths of the LRCJ columns are attributed by tabulary in proportion to the observed shares in a first pass where the table cells are rendered at their natural “horizontal” widths.

By default, Sphinx uses a table layout with J for every column.

0.3 新版功能.

在 1.6 版更改: Merged cells may now contain multiple paragraphs and are much better handled, thanks to custom Sphinx LaTeX macros. This novel situation motivated the switch to J specifier and not L by default.

提示

Sphinx actually uses T specifier having done \newcolumntype{T}{J}. To revert to previous default, insert \newcolumntype{T}{L} in the LaTeX preamble (see latex_elements).

A frequent issue with tabulary is that columns with little contents are “squeezed”. The minimal column width is a tabulary parameter called \tymin. You may set it globally in the LaTeX preamble via \setlength{\tymin}{40pt} for example.

Else, use the tabularcolumns directive with an explicit p{40pt} (for example) for that column. You may use also l specifier but this makes the task of setting column widths more difficult if some merged cell intersects that column.

警告

Tables with more than 30 rows are rendered using longtable, not tabulary, in order to allow pagebreaks. The L, R, … specifiers do not work for these tables.

Tables that contain list-like elements such as object descriptions, blockquotes or any kind of lists cannot be set out of the box with tabulary. They are therefore set with the standard LaTeX tabular (or longtable) environment if you don’t give a tabularcolumns directive. If you do, the table will be set with tabulary but you must use the p{width} construct (or Sphinx’s \X and \Y specifiers described below) for the columns containing these elements.

Literal blocks do not work with tabulary at all, so tables containing a literal block are always set with tabular. The verbatim environment used for literal blocks only works in p{width} (and \X or \Y) columns, hence Sphinx generates such column specs for tables containing literal blocks.

Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a backslash in the specifier letter). It is like p{width} with the width set to a fraction a/b of the current line width. You can use it in the tabularcolumns (it is not a problem if some LaTeX macro is also called \X.)

It is not needed for b to be the total number of columns, nor for the sum of the fractions of the \X specifiers to add up to one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and the table will occupy 80% of the line width, the first of its three columns having the same width as the sum of the next two.

This is used by the :widths: option of the table directive.

Since Sphinx 1.6, there is also the \Y{f} specifier which admits a decimal argument, such has \Y{0.15}: this would have the same effect as \X{3}{20}.

在 1.6 版更改: Merged cells from complex grid tables (either multi-row, multi-column, or both) now allow blockquotes, lists, literal blocks, … as do regular cells.

Sphinx’s merged cells interact well with p{width}, \X{a}{b}, \Y{f} and tabulary’s columns.

备注

tabularcolumns conflicts with :widths: option of table directives. If both are specified, :widths: option will be ignored.

Math

The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no further translation is necessary when building LaTeX output.

Keep in mind that when you put math markup in Python docstrings read by autodoc, you either have to double all backslashes, or use Python raw strings (r"raw").

.. math::

Directive for displayed math (math that takes the whole line for itself).

The directive supports multiple equations, which should be separated by a blank line:

.. math::

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

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

In addition, each single equation is set within a split environment, which means that you can have multiple aligned lines in an equation, aligned at & and separated by \\:

.. math::

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

For more details, look into the documentation of the AmSMath LaTeX package.

When the math is only one line of text, it can also be given as a directive argument:

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

Normally, equations are not numbered. If you want your equation to get a number, use the label option. When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. See eq for an example. The numbering style depends on the output format.

There is also an option nowrap that prevents any wrapping of the given math in a math environment. When you give this option, you must make sure yourself that the math is properly set up. For example:

.. math::
   :nowrap:

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

参见

Math support for HTML outputs in Sphinx

Rendering options for math with HTML builders.

latex_engine

Explains how to configure LaTeX builder to support Unicode literals in math mark-up.

语法制作显示

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

.. productionlist:: [productionGroup]

该指令用于包围一组产品。每个产品都在一行中给出，由一个名称组成，用冒号与下面的定义分开。如果定义跨越多行，每一个延续行都必须以冒号开始，放在与第一行相同的列中。productionlist 指令参数中不允许有空行。

定义可以包含形符为解释性文本的形符名称（例如，”sum ::= `integer` "+" `integer`”）—— 这产生了对这些形符的生产的交叉引用。在生产列表之外，你可以使用 token 来引用形符的生产。

productionlist 的 productionGroup 参数用于区分属于不同语法的不同生产列表集。因此，具有相同 productionGroup 的多个生产列表在同一范围内定义规则。

在生产列表中，形符隐含地指代了当前组的生产。你可以通过在形符前加上组名和冒号来指代另一个语法的生产，例如：”otherGroup:sum”。如果形符的组不应该显示在生产中，可以在前面加上一个斜体字，例如，”~otherGroup:sum”。如果要从一个未命名的语法中引用一个生产，形符应以冒号为前缀，例如，”:sum”。

在生产列表之外，如果你给了一个 productionGroup 参数，你必须在交叉引用中的形符名称前加上组名和冒号，例如，”myGroup:sum”，而不是仅仅 “sum”。如果组不应该显示在链接的标题中，可以给出一个明确的标题（例如，”myTitle <myGroup:sum>”），或者在目标前加上一个斜体字（例如，”~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`

脚注

1

LaTeX writer 只参考文档中第一个 toctree 指令的 maxdepth 选项。

2

关于可用的 globbing 语法的说明：你可以使用标准的 shell 结构 *、?、[...] 和 [!...]，其特点是这些都不匹配斜线。双星 ** 可以用来匹配任何字符序列，包括 斜线。

3

有一个标准的 .. include 指令，但是如果没有找到文件，它会产生错误。这个指令只发出一个警告。

4

对于大多数构建器来说，名称和格式是一样的。目前，只有从 html 构建器衍生出来的构建器才会区分构建器格式和构建器名称。

注意，当前的构建器标签在 conf.py 中不可用，只有在构建器被初始化后才可用。