reStructuredText 基础¶
RestructuredText是Sphinx使用的默认纯文本标记语言。本节简要介绍 reStructuredText（REST）的概念和语法，旨在为作者提供足够的信息，以便高效地编写文档。由于REST被设计成一种简单、不引人注目的标记语言，所以这不会花费太长时间。
参见
权威人士 reStructuredText User Documentation 。本文档中的“ref”链接指向REST参考中各个构造的描述。
段落¶
段落 (ref ）是REST文档中最基本的块。段落只是由一个或多个空行分隔的文本块。与Python一样，缩进在REST中很重要，因此同一段落的所有行必须与缩进的同一级别保持对齐。
内联标记¶
标准的REST内联标记非常简单：使用
星号：
*text*强调（斜体）两个星号：
**text**用于强调（粗体），以及背引号：
``text``代码示例。
如果星号或反引号出现在正在运行的文本中，并且可能与内联标记分隔符混淆，则必须用反斜杠对它们进行转义。
请注意此标记的某些限制：
不能嵌套，
内容不能以空格开头或结尾：
* text*是错的，它必须用非文字字符与周围的文本分隔开。使用反斜杠转义的空格来解决这个问题：
thisis\ *one*\ word.
这些限制可能在将来的docutils版本中解除。
也可以用角色替换或扩展一些内嵌标记。参照 角色 更多信息。
像块一样的列表和引号¶
列表标记 (ref ）很自然：只需在段落的开头放一个星号，并适当缩进即可。编号列表也是如此；它们也可以使用 # 标志：：
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
嵌套列表是可能的，但请注意，它们必须用空行与父列表项分隔：
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
定义列表 (ref ）创建如下：
term (up to a line of text)
Definition of the term, which must be indented
and can even consist of multiple paragraphs
next term
Description.
请注意，术语不能有多行文本。
引用的段落 (ref ）只需将它们缩进超过周围段落即可创建。
线块 (ref ）是保留换行符的方法：
| These lines are
| broken exactly like in
| the source file.
还有几个更特殊的模块可用：
文字块¶
文字代码块 (ref ）以特殊标记结束段落 :: . 文本块必须缩进（和所有段落一样，用空行与周围段落分隔）：：
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
处理 :: 标记很智能：
如果它是以自己的段落出现的，则该段落完全不在文档中。
如果前面有空白，则删除标记。
如果前面有非空白，则标记将被单个冒号替换。
这样，上面示例第一段中的第二句话将被表示为“下一段是代码示例：”。
可以在文档范围内为这些文本块启用代码突出显示，方法是使用 highlight 在整个项目范围内，使用 highlight_language 配置选项。这个 code-block 指令可用于逐块设置突出显示。这些指令稍后讨论。
测试块¶
测试块 (ref ）是交互式python会话剪切并粘贴到docstring中。他们不需要 literal blocks 语法。doctest块必须以空行结尾，并且应该 not 以未使用的提示结束：
>>> 1 + 1
2
表格¶
为了 网格表 (ref ）您必须自己“绘制”单元格网格。它们看起来像这样：
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
简单表 (ref ）更容易编写，但有限：它们必须包含多行，并且第一列单元格不能包含多行。它们看起来像这样：
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
还支持两种语法： CSV表 和 列表表 . 他们使用 显式标记块 . 参照 表格 更多信息。
超链接¶
外部链接¶
使用 `Link text <https://domain.invalid/>`_ 对于内联Web链接。如果链接文本应该是网址，则根本不需要特殊标记，解析器会在普通文本中查找链接和邮件地址。
重要
链接文本和URL的开头之间必须有空格。
还可以分离链接和目标定义 (ref ，像这样：
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
内部链接¶
内部链接是通过sphinx提供的特殊rest角色完成的，请参见特定标记部分， 交叉引用任意位置 .
小节¶
剖面标头 (ref ）通过使用标点符号在节标题上加下划线（也可以选择在节标题上加下划线）创建，至少与文本一样长：
=================
This is a heading
=================
通常情况下，不会将标题级别分配给某些字符，因为结构是根据标题的顺序确定的。但是，此约定用于 Python Developer's Guide for documenting 你可以遵循这一点：
#带上横线，用于零件*带上横线，用于章节=对于各节-适用于小节^适用于小节"对于段落
当然，您可以自由地使用自己的标记字符（参见其余文档），并使用更深的嵌套级别，但请记住，大多数目标格式（HTML、LaTex）支持的嵌套深度有限。
字段列表¶
字段列表 (ref ）字段序列是否标记如下：
:fieldname: Field content
它们通常用于python文档：
def my_function(my_arg, my_other_arg):
"""A function just for me.
:param my_arg: The first of my arguments.
:param my_other_arg: The second of my arguments.
:returns: A message (just for me, of course).
"""
sphinx扩展了标准docutils行为，并拦截了文档开头指定的字段列表。参照 字段列表 更多信息。
角色¶
角色或“自定义解释文本角色” (ref )是一段内联的显式标记。它意味着所附文本应以特定方式解释。Sphinx使用它来提供语义标记和标识符的交叉引用，如相应小节中所述。其一般语法为 :rolename:`content `。
docutils支持以下角色：
emphasis -- equivalent of
*emphasis*strong -- equivalent of
**strong**literal -- equivalent of
``literal``subscript --下标文本
superscript --上标文本
title-reference --书籍、期刊和其他材料的标题
参照 角色 为Sphinx添加的角色。
显式标记¶
“显式标记” (ref ）在REST中用于大多数需要特殊处理的结构，如脚注、特别突出显示的段落、注释和一般指令。
显式标记块以一行开头 .. 后面是空白，最后是同一缩进级别的下一段。（在显式标记和普通段落之间需要有空行。这听起来可能有点复杂，但当你写的时候，它就足够直观了。）
指令¶
指示 (ref ）是显式标记的通用块。除了角色之外，它也是 reST 的延伸机制之一，Sphinx对其进行了大量的利用。
docutils支持以下指令：
警告： attention ， caution ， danger ， error ， hint ， important ， note ， tip ， warning 和一般的 admonition . （大多数主题样式只有“注释”和“警告”两种。）
图像：
附加车身元件：
contents （本地文件，即仅限当前文件、目录）
container （具有自定义类的容器，用于生成外部
<div>在HTML中）rubric （与文件分割无关的标题）
parsed-literal （支持内联标记的文本块）
epigraph （带可选属性行的块引号）
highlights ， pull-quote （带自己的类属性的块引号）
compound （复合段）
特殊表格：
table （有标题的表格）
csv-table （由逗号分隔值生成的表）
list-table （从列表列表生成的表）
特别指示：
HTML细节：
影响标记：
default-role （设置新的默认角色）
role （创建新角色）
因为这些只是每个文件，所以最好使用Sphinx的设施来设置
default_role.
Sphinx添加的指令在 指令 .
基本上，指令由名称、参数、选项和内容组成。（记住这个术语，它在下一章中用于描述自定义指令。）看看这个例子：
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function 是指令名。这里给出了两个参数，第一行和第二行的剩余部分，以及一个选项。 module （如您所见，选项在参数后面的行中给出，并由冒号表示）。选项必须缩进到与指令内容相同的级别。
指令内容跟随在空行之后，并且相对于指令开始缩进，或者如果存在选项，则缩进与选项相同的量。
请注意，缩进不是固定数量的空格，例如三个，而是任意数量的空格。当在整个文档中使用固定缩进时，这可能会令人惊讶，并且可能会对对空格敏感的指令产生影响。比较：
.. code-block::
:caption: A cool example
The output of this line starts with four spaces.
.. code-block::
The output of this line has no spaces at the beginning.
在第一个代码块中，选项行将内容的缩进固定为三个空格，因此内容以四个空格开始。在后者中，缩进由内容本身固定为七个空格，因此它不是以空格开始的。
图像¶
REST支持图像指令 (ref ，使用方式如下：
.. image:: gnu.png
(options)
在Sphinx中使用时，给出的文件名（此处 gnu.png ）必须是相对于源文件的，或者是绝对的，这意味着它们是相对于顶级源目录的。例如，文件 sketch/spam.rst 可以参考图像 images/spam.png 作为 ../images/spam.png 或 /images/spam.png .
sphinx将自动将图像文件复制到建筑物上输出目录的子目录（例如 _static 用于HTML输出的目录。）
图像大小选项的解释 (width 和 height ）如下所示：如果大小没有单位或单位是像素，则给定的大小仅适用于支持像素的输出通道。其他单位（如 pt 将用于HTML和LaTex输出（后者替换为 pt 通过 bp 因为这是特克斯单位，所以 72bp=1in ）
sphinx通过允许星号作为扩展名来扩展标准docutils行为：
.. image:: gnu.*
然后，Sphinx搜索与提供的模式匹配的所有图像，并确定其类型。然后，每个构建者从这些候选对象中选择最佳的图像。例如，如果文件名 gnu.* 提供了两份文件 gnu.pdf 和 gnu.png 在源代码树中， Latex 生成器将选择前者，而HTML生成器将选择后者。支持的图像类型和选择优先级定义在 Builders .
请注意，图像文件名不应包含空格。
在 0.4 版本发生变更: 添加了对以星号结尾的文件名的支持。
在 0.6 版本发生变更: 图像路径现在可以是绝对的。
在 1.5 版本发生变更: Latex 目标支持像素（默认为 96px=1in ）
脚注¶
脚注 (ref ）、使用 [#name]_ 标记脚注位置，并将脚注正文添加到文档底部的“footnotes”标题后面，如：
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
你也可以明确地给脚注编号。 ([1]_ ）或者使用不带名称的自动编号脚注 ([#]_ ）
引文¶
标准 reST 引文 (ref ）支持，具有“全局”的附加功能，即可以从所有文件中引用所有引文。像这样使用它们：
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引文用法类似于脚注用法，但标签不是数字或以开头 # .
替代品¶
reST 支持“替换” (ref ，这是文本中引用的文本和/或标记 |name| . 它们被定义为带有显式标记块的脚注，如下所示：
.. |name| replace:: replacement *text*
或者：
.. |caution| image:: warning.png
:alt: Warning!
见 reST reference for substitutions 有关详细信息。
如果您希望使用某些替换来替换所有文档，请将它们放入 rst_prolog 或 rst_epilog 或将它们放入单独的文件中，并将其包含在要在其中使用它们的所有文档中。 include 指令。(请确保为包含文件提供与其他源文件不同的文件扩展名，以避免Sphinx将其视为独立文档。)
sphinx定义了一些默认替换，请参见 替代品 .
HTML元数据¶
这个 meta 指令允许指定 metadata element Sphinx文档页面的。例如，指令：：
.. meta::
:description: The Sphinx documentation builder
:keywords: Sphinx, documentation, builder
将生成以下HTML输出：
<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">
另外，sphinx会将meta指令中指定的关键字添加到搜索索引中。因此， lang 考虑元元素的属性。例如，指令：
.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
将以下单词添加到具有不同语言配置的生成的搜索索引中：
pleasefindthiskey，pleasefindthiskeytoo到 英语 建造；bittediesenkeyfinden到 德国的 建造；backup以所有语言构建。
信源编码¶
由于在REST中包含特殊字符（如em短划线或版权标志）的最简单方法是直接将它们写为Unicode字符，因此必须指定编码。默认情况下，sphinx假定源文件以utf-8编码；您可以使用 source_encoding 配置值。
高查斯¶
在编写REST文档时，通常会遇到一些问题：
内联标记的分离： 如上所述，内联标记跨度必须用非单词字符与周围的文本分隔开，您必须使用反斜杠转义空格来绕过这一点。见 the reference 有关详细信息。
没有嵌套的内联标记： 类似的东西
*see :func:`foo`*不可能。
评论¶
每个不是有效标记构造的显式标记块（如上面的脚注）都被视为注释。 (ref ）例如：：
.. This is a comment.可以在注释开始后缩进文本以形成多行注释：：