指令

As previously discussed 指令是显式标记的一般块。虽然docutils提供了许多指令，但sphinx提供了更多的指令，并将指令用作主要的扩展机制之一。

看见 领域 用于按域添加的角色。

参见

参考 reStructuredText Primer 有关docutils提供的指令的概述。

目录

由于REST没有连接多个文档或将文档拆分为多个输出文件的功能，因此Sphinx使用自定义指令在文档所组成的单个文件和目录之间添加关系。这个 toctree 指令是中心元素。

备注

一个文件在另一个文件中的简单“包含”可以通过 include 指令。

备注

要为当前文档（.rst文件）创建目录，请使用标准的REST contents directive .

.. toctree::

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

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

考虑这个例子（摘自python docs的库引用索引）：：

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

这可以完成两件事：

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

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

Entries

文档标题 toctree 将自动从引用文档的标题中读取。如果这不是您想要的，您可以使用类似的语法来指定一个显式的标题和目标来放置超链接（和sphinx的 cross-referencing syntax ）这看起来像：

.. toctree::

   intro
   All about strings <strings>
   datatypes

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

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

章节编号

如果希望在HTML输出中包含节号，请给出 顶层 托克特里亚 numbered 选择权。例如：：

.. toctree::
   :numbered:

   foo
   bar

编号从标题开始 foo . 子目录树自动编号（不要给出 numbered 给那些人打旗子。

通过将深度作为数字参数赋予 numbered .

其他选项

你可以使用 caption 选项来提供目录树标题，并且可以使用 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指令的文档。如果您想从目录树生成“站点地图”，这很有用。

你可以使用 reversed 标记选项以颠倒列表中条目的顺序。这在使用 glob 用于反转文件顺序的标志选项。例子：：

.. toctree::
   :glob:
   :reversed:

   recipe/*

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

.. toctree::
   :hidden:

   doc_1
   doc_2

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

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

.. toctree::
   :includehidden:

   doc_1
   doc_2

所有其他目录树条目都可以通过“隐藏”选项消除。

最后，所有文档 source directory （或子目录）必须出现在 toctree 指令；如果sphinx发现一个未包含的文件，它将发出警告，因为这意味着该文件将无法通过标准导航访问。

使用 exclude_patterns 从构建中显式地排除文档或目录。使用 the "orphan" metadata 允许创建文档，但通知Sphinx无法通过目录树访问该文档。

“根文档”(由选择 root_doc )是TOC树层次结构的“根”。它可以用作文档的主页，或者如果您不给出 maxdepth 选择。

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

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

在 1.0 版本发生变更: 添加了“仅标题”选项。

在 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.
.. versionremoved:: version

类似于 versionadded ，但描述了删除该功能的时间。可以提供解释，以告知读者使用什么，或者为什么删除该功能。示例：：

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

Added in version 7.3.

.. 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 <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 版本弃用: 此仅限演示的指令是旧版本的遗留内容。使用 rst-class 指令，并添加适当的样式。

.. hlist::

此指令必须包含项目符号列表。它将通过水平分布多个项目，或者根据生成器减少项目之间的间距，将其转换为更紧凑的列表。

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

.. hlist::
   :columns: 3

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

Added in version 0.6.

显示代码示例

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

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

在所有情况下，语法突出显示都由 Pygments 。在使用文字块时，这是使用任何 highlight 源文件中的指令。当一个 highlight 指令，则该指令将一直使用到下一个 highlight 指令。如果没有 highlight 指令，则使用全局突出显示语言。该默认为 python 但是可以使用 highlight_language 配置值。支持下列值：

  • none （无突出显示）

  • default （类似于 python3 但却退缩到 none 不带警告的突出显示失败；默认情况下 highlight_language 未设置）

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

  • python

  • rest

  • c

  • …以及其他 lexer alias that Pygments supports

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

重要

支持的lexer别名列表绑定到pygment版本。如果要确保一致的突出显示，应该修复您的Pygments版本。

.. highlight:: language

例子：：

.. highlight:: c

这种语言一直使用到下一个 highlight 遇到指令。如前所述， 语言 可以是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.

指令的别名 sourcecode 也很管用。此指令以语言名称作为参数。它可以是 any lexer alias supported by Pygments 。如果未给出，则 highlight 指令将被使用。如果未设置， highlight_language 将会被使用。显示代码示例 inline 在其他文本中，而不是作为单独的块，可以使用 code 而不是角色。

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

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)

定义可通过使用 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.

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个字符。如果未给出参数，将通过以下方式删除前导空格 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 指令。 [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

这将只包括属于 start() 方法在 Timer 文件中的类。

或者，您可以通过给出 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 跳过第一行）。

备注

如果只想选择 [second-section] 的ini文件如下所示，您可以使用 :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 and append option, respectively. This is useful e.g. for highlighting PHP code that doesn't include the <?php/?> 标记。

如果要显示代码的差异，可以通过提供 diff 选项：

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

这显示了 example.py 和 example.py.orig 具有统一的diff格式。

A 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 被认为具有行号 1 对于 lines .

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

与常规定义列表相比， 倍数 每个条目允许使用术语，并且术语中允许使用内联标记。您可以链接到所有术语。例如：：

.. glossary::

   term 1
   term 2
      Definition of both terms.

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

如果要为常规索引项指定“分组键”，可以将“键”设置为“term:key”。例如：：

.. glossary::

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

请注意，“key”用于按原样对key进行分组。“key”不是标准化的；key“a”和“a”变为不同的组。“key”中的整个字符用于代替第一个字符；它用于“组合字符序列”和“代理项对”分组键。

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

Added in version 0.6: 现在可以给术语表指令a :sorted: 自动按字母顺序排序的标志。

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

在 1.4 版本发生变更: 应考虑词汇表术语的索引键 实验的 .

在 4.4 版本发生变更: 在国际化文档中， :sorted: FLAG根据翻译的术语进行排序。

元信息标记

.. 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
   pair: module; __main__
   pair: module; sys
   triple: module; search; path
   seealso: scope

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

...

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

由于index指令在源代码中的位置生成交叉引用目标，因此将它们放在一起是有意义的。 之前 它们所指的东西——例如一个标题，如上例所示。

可能的条目类型有：

单一的

创建单个索引项。可以通过用分号分隔子条目文本来使其成为子条目(下面还使用该符号来描述创建了什么条目)。例如：

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

  • single: execution 创建带标签的索引项 execution 。

  • single: execution; context 创建以下项的子项 execution 已贴标签 context 。

一对

创建两个索引项的快捷方式。这对值必须用分号分隔。示例：

.. index:: pair: loop; statement

这将创建两个索引项； loop; statement 和 statement; loop 。

三倍的

创建三个索引项的快捷方式。所有三个值都必须用分号分隔。示例：

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

这将创建三个索引项； module; search path ， search; path, module ，以及 path; module search 。

看见

创建引用另一个条目的索引项的快捷方式。示例：

.. index:: see: entry; other

这将创建一个引用 entry 至 other (即“条目”：见“其他”)。

锯齿波

喜欢 see ，但插入“See Also”而不是“See”。

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

这些 deprecated 所有快捷方式都会创建两个索引项。例如, module: hashlib 创建条目 module; hashlib 和 hashlib; module 。

自 1.0 版本弃用: 这些特定于Python的条目类型已弃用。

在 7.1 版本发生变更: 删除版本设置为Sphinx 9.0。现在使用这些条目类型将发出警告，并显示 index 类别。

您可以用感叹号在“主”索引项前加前缀，从而对其进行标记。生成的索引中强调了对“主”条目的引用。例如，如果两页包含：

.. index:: Python

一页包含：

.. index:: ! Python

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

对于只包含“单个”条目的索引指令，有一个速记符号：

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

这将创建四个索引项。

在 1.1 版本发生变更: 补充 see 和 seealso 类型以及标记主条目。

选项

:name: a label for hyperlink (text)

定义可通过使用 ref . 例如：：

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

Added in version 3.0.

:index:

而 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

未定义的标记是假的、已定义的标记(通过 -t 命令行选项或在 conf.py ，见 here )都是真的。布尔表达式，也使用圆括号(如 (latex or html) and draft )被支持。

这个 格式 以及 name 当前生成器的 (html ， latex 或 text ）始终设置为标记 [4]. 为了明确区分格式和名称，还添加了前缀 format_ 和 builder_ 例如，epub builder定义了标签 html ， epub ， format_html 和 builder_epub .

设置了这些标准标签 之后 配置文件已被读取，因此它们在那里不可用。

所有标记必须遵循标准的python标识符语法，如 Identifiers and keywords 文档。也就是说，标记表达式只能由符合Python变量语法的标记组成。在ASCII中，它由大小写字母组成。 A 通过 Z ，下划线 _ 除第一个字符外，数字 0 通过 9 .

Added in version 0.6.

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

警告

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

表格

使用 reStructuredText tables ，即

这个 table 指令用作 grid 和 简单的 句法。

它们在HTML输出中工作得很好，但将表格呈现为LaTeX很复杂。查看 latex_table_style 。

在 1.6 版本发生变更: 从包含复杂内容的网格表(如多个段落、块引号、列表、文字块)中合并的单元格(多行、多列，两者)将正确地呈现为LaTeX输出。

.. tabularcolumns:: column spec

该指令只影响SOURCE中下一个表的LaTeX输出。强制参数是列规范(在LaTeX习惯用法中称为“对齐前导”)。请参阅LaTeX文档，如 wiki page ，了解此类柱规格的基础知识。

Added in version 0.3.

备注

tabularcolumns 与冲突 :widths: 表指令选项。如果两者都有规定， :widths: 选项将被忽略。

Sphinx将呈现包含30多行的表 longtable 。除了 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{width} 使用显式 width (或 \X{a}{b} 或 \Y{f} )。

  • 文字块不适用于 tabulary 完全没有。Sphinx将退回到 tabular 或 longtable 环境，并生成合适的柱规格。

在缺少 tabularcolumns 指令，并且对于上面警告中描述的最多包含30行且没有问题单元格的表，Sphinx使用 tabulary 以及 J 列-每列的类型。

在 1.6 版本发生变更: 以前， L 使用了列型(文本左对齐)。要恢复到这一点，请包括 \newcolumntype{T}{L} 在LaTeX的序言中，Sphinx实际上使用了 T 并将其默认设置为的别名 J 。

提示

一个常见的问题是 tabulary 内容很少的栏目似乎被“挤压”了。例如，可以添加到 Latex 前导码 \setlength{\tymin}{40pt} 以确保最小列宽为 40pt vt.的. tabulary 默认为 10pt 太小了。

提示

强制使用 Latex longtable 环境通行证 longtable 作为一名 :class: 选项以 table ， csv-table ，或 list-table 。使用 rst-class 对于其他桌子。

数学

数学的输入语言是 Latex 标记。这是纯文本数学符号的事实上的标准，并且有一个额外的优点，即在构建 Latex 输出时不需要进一步的翻译。

记住，当您将数学标记放入 python文档字符串 通过阅读 autodoc ，或者必须将所有反斜杠加倍，或者使用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 package .

当数学仅为一行文本时，也可以将其作为指令参数提供：

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

通常，方程不编号。如果你想要你的方程得到一个数字，用 label 选择权。当给定时，它会为公式选择一个内部标签，通过该标签可以交叉引用，并导致发布公式编号。见 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]

此指令用于封装一组产品。每个产品都在一行中给出，并且由一个名称组成，名称之间用冒号隔开，定义如下。如果定义跨越多行，则每个继续行必须以冒号开头，该冒号位于与第一行相同的列。内不允许有空行 productionlist 指令参数。

定义可以包含标记为解释文本的标记名称(例如，“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 。

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

在生产列表中，令牌隐式引用来自当前组的生产。您可以通过在标记前面加上组名和冒号来引用另一种语法的生成，例如，“therGroup：sum”。如果在生产中不应该显示令牌所在的组，则可以使用波浪号作为前缀，例如“~therGroup：sum”。要引用来自未命名语法的结果，标记应以冒号作为前缀，例如，“：sum”。

在生产列表之外，如果您给出了 生产组 参数，则必须在交叉引用中为内标识名称加上组名和冒号作为前缀，例如，“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`

脚注