指令

As previously discussed 指令是显式标记的泛型块。Docutils提供了许多指令,而Sphinx提供了更多指令,并使用指令作为主要的扩展机制之一。

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

参见

请参阅 reStructuredText Primer 以获取Docutils提供的指令的概述。

目录

由于REST不具备互连多个文档或将文档拆分为多个输出文件的功能,因此Sphinx使用定制指令来添加组成文档的单个文件和目录之间的关系。这个 toctree 指令是核心要素。

备注

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

备注

要为当前文档(.rst文件)创建目录,请使用标准REST contents directive

.. toctree::

该指令使用指令体中给出的文档的各个目录(包括“子目录树”),在当前位置插入“目录树”。相对文档名称(不是以斜杠开头)相对于出现指令的文档,绝对名称相对于源目录。A数字 maxdepth 可以提供选项来指示树的深度;默认情况下,包括所有级别。 [1]

“TOC树”的表示形式在每种输出格式中都有所不同。输出多个文件(例如Html)将其视为超链接的集合。另一方面,输出单个文件(例如,LaTeX、手册页等)将其替换为目录树上的文档内容。

考虑这个例子(取自Python文档的库参考索引):

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

这可以完成两件事:

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

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

Entries

中的文档标题 toctree 将自动从引用文档的标题中读取。如果这不是您想要的,您可以使用类似于REST超链接(和Sphinx的)的语法来指定明确的标题和目标 cross-referencing syntax )。这看起来像::

.. toctree::

   intro
   All about strings <strings>
   datatypes

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

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

Section numbering

如果您希望即使在HTML输出中也有节号,请给出 toplevel Toctree a numbered 选择。例如::

.. toctree::
   :numbered:

   foo
   bar

然后,编号从标题开始 foo 。子目录树会自动编号(不要给出 numbered 旗帜传给那些人)。

通过将深度作为数字参数提供给 numbered

Additional options

您可以使用 caption 选项来提供toctree标题,您可以使用 name 选项以提供隐式目标名称,该名称可通过使用 ref **

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

   foo

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

.. toctree::
   :titlesonly:

   foo
   bar

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

.. toctree::
   :glob:

   intro*
   recipe/*
   *

这首先包括名称以开头的所有文档 intro 中的所有文档。 recipe 文件夹,然后是所有剩余的文档(当然,包含该指令的文档除外)。 [2]

特殊条目名称 self 表示包含toctree指令的文档。如果您想要从toctree生成一个“站点地图”,这是很有用的。

您可以使用 reversed 用于颠倒列表中条目顺序的标志选项。这在使用 glob 用于颠倒文件顺序的标志选项。示例::

.. toctree::
   :glob:
   :reversed:

   recipe/*

您还可以为指令指定一个“隐藏”选项,如下所示:

.. toctree::
   :hidden:

   doc_1
   doc_2

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

如果您只想拥有一个顶级目录树并隐藏所有其他较低级别的目录树,您可以在顶级目录树条目中添加“包含隐藏”选项::

.. toctree::
   :includehidden:

   doc_1
   doc_2

然后,所有其他的TocTree条目都可以通过“隐藏”选项来消除。

最后,文件中的所有文档 source directory (或子目录)必须出现在某些 toctree 指令;如果Sphinx发现没有包含的文件,它将发出警告,因为这意味着无法通过标准导航访问该文件。

使用 exclude_patterns 显式地将文档或目录从生成中完全排除。使用 the "orphan" metadata 允许构建文档,但通知Sphinx无法通过toctree访问该文档。

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

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

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

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

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

在 1.2 版本发生变更: 增加了“包含隐藏”选项。

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

特殊名称

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中的项目版本。当这适用于整个模块时,它应该放在模块部分的顶部,在任何散文之前。

必须提供第一个参数,并且该参数是有问题的版本;您可以添加第二个参数,该参数由 brief 对变更的解释。

示例::

.. 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 版本加入: 缩写形式。

.. 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中显示语法突出显示的文字代码块:

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

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

  • none (不突出显示)

  • default (类似于 python3 但随着退而求其次 none 在没有警告的情况下突出显示失败;在 highlight_language 未设置)

  • guess (让Pygments根据内容猜测词法分析器,仅适用于某些可识别的语言)

  • python

  • rest

  • c

  • ..。以及任何其他 lexer alias that Pygments supports

如果用所选语言高亮显示失败(即Pygments发出“ERROR”标记),则不会以任何方式突出显示该块。

重要

支持的词法分析器别名列表与Pygment版本相关。如果你想确保一致的高亮显示,你应该修正你的俾格森版本。

.. highlight:: language

示例::

.. highlight:: c

这种语言将一直使用到下一年 highlight 指令。如前所述, language 可以是Pygments支持的任何词法分析器别名。

选项

:linenothreshold: threshold (number (optional))

启用以生成代码块的行号。

此选项采用可选数字作为阈值参数。如果给定任何阈值,该指令将只为长度超过N行的代码块生成行号。如果未指定,则将为所有代码块生成行号。

示例::

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

如果给定,突出显示的小错误将被忽略。

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

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

为了交叉引用代码块,可以使用 refnumref 角色,则有必要同时 namecaption 被定义。的论据 name 然后可以提供给 numref 以生成交叉引用。示例::

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

使用时 ref ,则可以生成交叉引用,仅 name 定义的,只要给出一个明确的标题。示例::

See :ref:`this code snippet <this-py>` for an example.

在 1.3 版本加入.

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

图形的类名。

在 1.4 版本加入.

: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

文件名通常相对于当前文件的路径。但是,如果它是绝对的(以 / ),它相对于顶层源目录。

Additional options

喜欢 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-afterend-before 选项(或仅其中之一)。如果 start-after 作为字符串选项提供,则只包括包含该字符串的第一行之后的行。如果 end-before 作为字符串选项提供,则只包括包含该字符串的第一行之前的行。这个 start-atend-at 选项的行为类似,但包含匹配字符串的行也包括在内。

start-after/start-atend-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.pyexample.py.orig 具有统一的DIFF格式。

A force 选项可以忽略突出显示时的小错误。

在 0.4.3 版本发生变更: 添加了 encoding 选择。

在 0.6 版本发生变更: 添加了 pyobjectlinesstart-afterend-before 选项以及对绝对文件名的支持。

在 1.0 版本发生变更: 添加了 prependappend ,以及 tab-width 选择。

在 1.3 版本发生变更: 添加了 difflineno-matchcaptionname ,以及 dedent 选择。

在 1.4 版本发生变更: 添加了 class 选择。

在 1.5 版本发生变更: 添加了 start-at ,以及 end-at 选择。

在 1.6 版本发生变更: 两者都有 start-afterlines 在使用中,第一行根据 start-after 被认为与行号相同 1lines

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

(对词汇表进行排序时,第一个术语确定排序顺序。)

如果您想为普通索引项指定“GROUPING KEY”,则可以将“KEY”设置为“Term:Key”。例如::

.. glossary::

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

请注意,“key”用于按原样分组key。“键”未规范化;键“A”和“a”成为不同的组。“key”中的整个字符用来代替第一个字符;它用于“组合字符序列”和“代理对”分组键。

在I18N情况下,即使原始文本只有“Term”部分,也可以指定“Localized Term:Key”。在这种情况下,翻译后的“本地化术语”将归入“关键字”组。

在 0.6 版本加入: 现在可以给词汇表指令一个 :sorted: 将自动按字母顺序对条目进行排序的标志。

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

在 1.4 版本发生变更: 应考虑术语表术语的索引键 experimental

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

元信息标记

.. sectionauthor:: name <email>

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

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

默认情况下,此标记不会以任何方式反映在输出中(它有助于跟踪贡献),但您可以设置配置值 show_authorsTrue 让他们在输出中产生一个段落。

.. codeauthor:: name <email>

这个 codeauthor 指令可以多次出现,它指定所描述代码的作者,就像 sectionauthor 说出一篇文献的作者(S)的名字。它也只在以下情况下才产生输出 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语句的确切位置(或在脱机媒体的情况下,链接到相应的页码)。

由于索引指令在它们在源代码中的位置生成交叉引用目标,因此将它们放入 before 他们所指的东西--例如,上面的例子中的标题。

可能的条目类型包括:

单人

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

.. index:: single: execution
           single: execution; context
  • single: execution 创建带标签的索引项 execution

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

成对

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

.. index:: pair: loop; statement

这将创建两个索引项; loop; statementstatement; loop

三重

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

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

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

看见

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

.. index:: see: entry; other

这将创建一个引用 entryother (即“条目”:见“其他”)。

另请参阅

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

模块、关键字、运算符、对象、异常、语句、构建

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

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

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

您可以通过在“主”索引项前面加上感叹号来标记这些索引项。在生成的索引中强调了对“主”条目的引用。例如,如果两个页面包含::

.. index:: Python

其中一页包含:

.. index:: ! Python

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

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

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

这将创建四个索引项。

在 1.1 版本发生变更: 增列 seeseealso 类型,以及标记主要条目。

选项

:name: a label for hyperlink (text)

定义可通过使用引用的隐式目标名称 ref 。例如::

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

在 3.0 版本加入.

:index:

而当 index 指令是块级标记并链接到下一段的开头,也有一个相应的角色直接设置使用它的链接目标。

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

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

在 1.1 版本加入.

包括基于标签的内容

.. only:: <expression>

包括指令的内容,仅当 expression 是真的。该表达式应由标记组成,如下所示::

.. only:: html and draft

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

这个 format 以及 name 当前构建者的 (htmllatextext )始终设置为标记 [4]. 为了明确区分格式和名称,它们还添加了前缀 format_builder_ 例如,epub构建器定义标签 htmlepubformat_htmlbuilder_epub

这些标准标签已设置 after 配置文件已读取,因此它们在那里不可用。

所有标签必须遵循标准的Python标识符语法,如 Identifiers and keywords 文件。也就是说,标记表达式可能只由符合Python变量语法的标记组成。在ASCII中,这由大写字母和小写字母组成 A 穿过 Z ,下划线 _ 并且,除第一个字符外,数字 0 穿过 9

在 0.6 版本加入.

在 1.2 版本发生变更: 添加了建造者的名称和前缀。

警告

此指令旨在仅控制文档的内容。它不能控制部分、标签等。

表格

使用 reStructuredText tables ,即任一

这个 table 指令充当可选的 gridsimple 语法。

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

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

.. tabularcolumns:: column spec

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

在 0.3 版本加入.

备注

tabularcolumns 与以下内容冲突 :widths: 表指令的选项。如果同时指定了两者, :widths: 选项将被忽略。

Sphinx将呈现包含30多行的表 longtable 。除了 lrcp{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 完全没有。狮身人面像将退回到 tabularlongtable 环境,并生成合适的柱规格。

在缺少 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: 选项以 tablecsv-table ,或 list-table 。使用 rst-class 对于其他桌子。

数学

数学的输入语言是LaTeX标记。这是纯文本数学表示法的事实标准,并且还有一个额外的优势,即在构建LaTeX输出时不需要进一步的转换。

请记住,在将数学标记放入 Python docstrings 阅读者 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生成器以支持数学标记中的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

这个 productionGroup 参数为 productionlist 用于区分属于不同语法的不同产生式列表集合。多个生产列表具有相同的 productionGroup 从而在相同的范围内定义规则。

在生产列表中,令牌隐式引用来自当前组的生产。您可以通过在令牌前面加上其组名和冒号来引用另一种语法的结果,例如,“therGroup:sum”。如果令牌的组不应该在生产中显示,可以在它前面加上一个波浪号,例如,“~therGroup: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`

脚注