reStructuredText 入门¶
reStructuredText 是 Sphinx 使用的默认纯文本标记语言。本节是对 reStructuredText (reST) 概念和语法的简要介绍，旨在为作者提供足够的信息以高效地编写文档。由于 reStructuredText 被设计成一种简单、不引人注目的标记语言，因此这不会花费太长时间。
另请参阅
权威的 reStructuredText 用户文档。本文档中的“ref”链接链接到 reStructuredText 参考中对各个构造的描述。
段落¶
段落 (ref) 是 reStructuredText 文档中最基本的块。段落只是用一个或多个空行分隔的文本块。与 Python 中一样，缩进在 reStructuredText 中很重要，因此同一段落的所有行都必须左对齐到相同的缩进级别。
行内标记¶
标准的 reStructuredText 行内标记非常简单：使用
一个星号：
*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.
对 :: 标记的处理是智能的
如果它作为自己的段落出现，则该段落完全从文档中省略。
如果它前面有空格，则标记将被删除。
如果它前面是非空格，则标记将替换为单个冒号。
这样，上面示例的第一个段落中的第二句话将呈现为“The next paragraph is a code sample:”。
可以使用 highlight 指令在文档范围内启用这些文字块的代码突出显示，并使用 highlight_language 配置选项在项目范围内启用。 code-block 指令可用于在逐块基础上设置突出显示。这些指令将在后面讨论。
Doctest 块¶
Doctest 块 (ref) 是剪切并粘贴到文档字符串中的交互式 Python 会话。它们不需要 文字块 语法。 doctest 块必须以空行结尾，并且不应以未使用的提示符结尾
>>> 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 链接。如果链接文本应该是 Web 地址，则根本不需要特殊标记，解析器会在普通文本中查找链接和邮件地址。
重要
链接文本和 URL 的开头 < 之间必须有一个空格。
您还可以分隔链接和目标定义 (ref)，如下所示
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
内部链接¶
内部链接是通过 Sphinx 提供的特殊 reStructuredText 角色完成的，请参阅有关特定标记的部分，交叉引用任意位置。
章节¶
章节标题 (ref) 的创建方式是用标点符号下划线（和可选的上划线）章节标题，至少与文本一样长
=================
This is a heading
=================
通常，没有标题级别分配给某些字符，因为结构是从标题的连续性确定的。但是，Python 开发者指南中用于文档记录使用了此约定，您可以遵循
#带上划线，表示部分*带上划线，表示章节=表示节-表示子节^表示子子节"表示段落
当然，您可以自由使用自己的标记字符（请参阅 reStructuredText 文档），并使用更深的嵌套级别，但请记住，大多数目标格式（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 – 等效于
*emphasis*strong – 等效于
**strong**literal – 等效于
``literal``subscript – 下标文本
superscript – 上标文本
title-reference – 用于书籍、期刊和其他材料的标题
有关 Sphinx 添加的角色，请参阅 角色。
显式标记¶
“显式标记” (ref) 在 reStructuredText 中用于大多数需要特殊处理的构造，例如脚注、特殊突出显示的段落、注释和通用指令。
显式标记块以以 .. 开头，后跟空格的行开始，并以相同缩进级别的下一个段落终止。（显式标记和普通段落之间需要有一个空行。当您编写它时，这一切听起来可能有点复杂，但它足够直观。）
指令¶
指令 (ref) 是通用的显式标记块。与角色一起，它是 reStructuredText 的扩展机制之一，Sphinx 大量使用它。
Docutils 支持以下指令
提示：attention、caution、danger、error、hint、important、note、tip、warning 和通用的 admonition。（大多数主题仅对“note”和“warning”进行特殊样式设置。）
图像
其他正文元素
contents（本地的，即仅适用于当前文件，内容表）
container（具有自定义类的容器，用于在 HTML 中生成外部
<div>）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.
在第一个代码块中，内容的缩进通过选项行固定为三个空格，因此内容以四个空格开头。在后者中，缩进由内容本身固定为七个空格，因此它不以空格开头。
图像¶
reStructuredText 支持图像指令 (ref)，用法如下
.. image:: gnu.png
(options)
在 Sphinx 中使用时，给定的文件名（此处为 gnu.png）必须相对于源文件，或者绝对路径，这意味着它们相对于顶级源目录。例如，文件 sketch/spam.rst 可以将图像 images/spam.png 引用为 ../images/spam.png 或 /images/spam.png。
Sphinx 将在构建时自动将图像文件复制到输出目录的子目录（例如，HTML 输出的 _static 目录。）
图像大小选项（width 和 height）的解释如下：如果大小没有单位或单位是像素，则给定的大小将仅对支持像素的输出通道有效。其他单位（如点的 pt）将用于 HTML 和 LaTeX 输出（后者将 pt 替换为 bp，因为这是 TeX 单位，使得 72bp=1in）。
Sphinx 通过允许星号作为扩展名来扩展标准 docutils 行为
.. image:: gnu.*
然后，Sphinx 搜索与提供的模式匹配的所有图像，并确定它们的类型。然后，每个构建器从这些候选项中选择最佳图像。例如，如果给定的文件名是 gnu.*，并且源树中存在两个文件 gnu.pdf 和 gnu.png，则 LaTeX 构建器将选择前者，而 HTML 构建器将首选后者。支持的图像类型和选择优先级在 构建器 中定义。
请注意，图像文件名不应包含空格。
版本 0.4 中修改: 添加了对以星号结尾的文件名的支持。
版本 0.6 中修改: 图像路径现在可以是绝对路径。
版本 1.5 中修改: latex 目标支持像素（默认值为 96px=1in）。
脚注¶
对于脚注 (ref)，使用 [#name]_ 标记脚注位置，并在文档底部在“脚注”标题下添加脚注正文，如下所示
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
您还可以显式编号脚注 ([1]_) 或使用没有名称的自动编号脚注 ([#]_)。
引文¶
支持标准的 reStructuredText 引文 (ref)，其附加功能是它们是“全局”的，即所有引文都可以从所有文件引用。像这样使用它们
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引文用法与脚注用法类似，但标签不是数字或以 # 开头。
替换¶
reStructuredText 支持“替换” (ref)，它们是在文本中用 |name| 引用的文本和/或标记片段。它们像脚注一样用显式标记块定义，如下所示
.. |name| replace:: replacement *text*
或这个
.. |caution| image:: warning.png
:alt: Warning!
有关详细信息，请参阅 reStructuredText 参考中的替换。
如果要对所有文档使用某些替换，请将它们放入 rst_prolog 或 rst_epilog 中，或将它们放入单独的文件中，并使用 include 指令将其包含在要使用它们的所有文档中。（请务必给包含文件一个与其他源文件不同的文件扩展名，以避免 Sphinx 将其作为独立文档查找。）
Sphinx 定义了一些默认替换，请参阅 替换。
HTML 元数据¶
meta 指令允许指定 Sphinx 文档页面的 HTML 元数据元素。例如，指令
.. 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 指令中指定的关键字添加到搜索索引中。因此，将考虑 meta 元素的 lang 属性。例如，指令
.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
将以下单词添加到具有不同语言配置的构建的搜索索引中
pleasefindthiskey,pleasefindthiskeytoo到英语构建；bittediesenkeyfinden到德语构建；backup到所有语言的构建。
源文件编码¶
由于在 reStructuredText 中包含特殊字符（如长破折号或版权符号）的最简单方法是直接将它们写为 Unicode 字符，因此必须指定编码。 Sphinx 默认假定源文件以 UTF-8 编码；您可以使用 source_encoding 配置值更改此设置。
陷阱¶
在编写 reStructuredText 文档时，人们经常会遇到一些问题
行内标记的分隔： 如上所述，行内标记跨度必须与周围的文本用非单词字符分隔，您必须使用反斜杠转义的空格来解决此问题。 有关详细信息，请参阅 参考。
没有嵌套的行内标记： 类似
*see :func:`foo`*的内容是不可能的。
注释¶
每个不是有效标记构造的显式标记块（如上面的脚注）都被视为注释 (ref)。例如
.. This is a comment.您可以在注释开始后缩进文本以形成多行注释