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.
对 :: 标记的处理很智能
如果它作为单独的一段出现，则该段将完全从文档中删除。
如果它前面有空格，则会删除该标记。
如果它前面是非空格，则该标记将替换为单个冒号。
这样，上面示例中第一段中的第二句话将呈现为“下一段是代码示例：”。
可以使用 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/>`_ 用于内联网络链接。如果链接文本应该是网络地址，则根本不需要特殊标记，解析器会在普通文本中找到链接和邮件地址。
重要
链接文本和 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 – 用于书籍、期刊和其他材料的标题
请参考 Roles 以了解 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 特性
meta（生成 HTML
<meta>标签，另请参见下面的 HTML Metadata）title（覆盖文档标题）
影响标记
default-role（设置一个新的默认角色）
role（创建一个新的角色）
由于这些仅针对每个文件，因此最好使用 Sphinx 的工具来设置
default_role。
Sphinx 添加的指令在 Directives 中描述。
基本上，指令由名称、参数、选项和内容组成。（记住这些术语，它们将在下一章中描述自定义指令时使用。）看一下这个例子，
.. 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 构建器将首选后者。支持的图像类型和选择优先级在 Builders 中定义。
请注意，图像文件名不应该包含空格。
Changed in version 0.4: 添加了对以星号结尾的文件名的支持。
Changed in version 0.6: 图像路径现在可以是绝对路径。
Changed in version 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]_）或使用没有名称的自动编号脚注（[#]_）。
引用¶
支持标准的 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 指令将其包含在您想要使用它们的每个文档中。（确保为 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 中包含特殊字符（如 em 破折号或版权符号）的最简单方法是直接将它们作为 Unicode 字符写入，因此必须指定编码。默认情况下，Sphinx 假定源文件使用 UTF-8 编码；您可以使用 source_encoding 配置值更改此设置。
注意事项¶
在编写 reStructuredText 文档时，人们经常会遇到一些问题
内联标记的分隔：如上所述，内联标记跨度必须与周围的文本用非单词字符分隔，您必须使用反斜杠转义的空格来解决此问题。请参阅 参考 以了解详细信息。
不允许嵌套的内联标记：例如
*see :func:`foo`*是不可能的。
注释¶
每个不是有效标记结构的显式标记块（如上面的脚注）都被视为注释（ref）。例如
.. This is a comment.您可以在注释开始后的文本中缩进以形成多行注释