reStructuredText 入门¶
reStructuredText 是 Sphinx 默认使用的纯文本标记语言。这个部分简要介绍 reStructuredText（reST） 的概念和语法，目标是给文档创作者足够的知识，提高工作效率。由于 reST 设计目标本来就是简单的标记语言，学起来也不会很费力。
参见
权威的 reStructuredText 用户文档。本文档中 ref 链接可以链接到 reST 参考文献中对各个结构体的描述。
段落¶
段落（ref）是 reST 文档中最基本的组成部分。段落就是大段的文字，段落之间可以有空行。如同 Python 一样，reST 中缩进也很重要，所以同一段落中的内容，左侧都要使用同样的缩进量。
行内标记¶
标准的 reST 行内标记非常简单，如下
一个星号：
*文本*表示强调（斜体），两个星号：
**文本**表示更加强调（粗体），以及反单引号：
``文本``表示代码样例。
如果文本中的星号或者反单引号可能被混淆为行内标记分隔符，添加反斜杠转义即可。
注意，这些标记有些功能限制：
不能嵌套，
标记内不能以空格开始：
* 文本*就不行，行内标记符号外只能是非文字字符。想写空格的话就要转义：
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 表 和 列表。它们使用显式标记块。参考 表格 获取更多信息。
超链接¶
外部链接¶
使用 `链接文本 <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
=================
通常，Sphinx 并未对某些字符分配标题级别，因为结构是从标题的连续性确定的。但是， Python 文档样式指南 中使用了下面的惯例，您可以参考该惯例：
#有上线，用于编（parts）*有上线，用于章（chapters）=for sections-for subsections^for subsubsections"for paragraphs
当然，您可以自由使用自己的标记字符（请参阅 reST 文档），并使用更深层次的嵌套级别，但请记住，大多数目标格式（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 使用它来提供语义标记和标识符的交叉引用，如相应部分所述。一般语法是 :角色名:`内容`。
Docutils 支持以下角色：
emphasis – 等价于
*emphasis*strong – 等价于
**strong**literal – 等价于
``literal``subscript – 下标文字
superscript – 上标文字
title-reference – 用于书籍、期刊和其他材料的标题
有关 Sphinx 添加的角色，请参阅 角色。
显式标记¶
“显式标记”（ref）在 reST 中用于大多数需要特殊处理的结构，例如脚注，特别突出显示的段落，注释和泛型指令。
一个显式标记块以 .. 开始，后面是 空格，并以同一缩进程度的下一个段落为结束。（显式标记和普通段落之间需要有一个空行。这可能听起来有点复杂，但是当你写它时它足够直观。）
指令¶
指令 (ref) 是一个通用的显式标记块。与角色一起，它是 reST 的扩展机制之一，Sphinx 大量使用了它。
Docutils 支持以下指令：
警告：attention、caution、danger、error、hint、important、note、tip、warning 以及泛型 admonition。（大多数主题仅限于 “note” 和 “warning”。）
图片
额外的 body 元素：
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.
在第一个代码块中，内容的缩进是由选项行固定为三个空格，接着，内容以四个空格。在后者中，内容本身的缩进被固定为七个空格，因此它没有以空格开始。
图片¶
reST 支持图像指令（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]_）或使用不带名字的自动编号脚注（[#]_）。
引文¶
支持标准 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 替换的引用 了解细节。
如果您想对所有文档使用某些替换，请将它们放入 rst_prolog 或 rst_epilog 或将它们放入一个单独的文件中，并将其包含在您想要使用它们的所有文档中，使用 include 指令。（一定要给 include 文件一个不同于其他源文件的文件扩展名，以避免 Sphinx 发现它是一个独立的文档。）
Sphinx 定义了一些默认替换，参见 替换。
HTML 元数据¶
meta 指令 (ref) 允许指定 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 元素的 lang 属性被考虑。例如，指令
.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
将以下单词添加到具有不同语言配置的构建的搜索索引中：
pleasefindthiskey、pleasefindthiskeytoo到 English 构建；bittediesenkeyfinden到 German 构建；backup以所有语言构建。
源编码¶
由于在 reST 中包含特殊字符（例如 em 破折号或版权符号）的最简单方法是将它们直接写为 Unicode 字符，因此必须指定编码。Sphinx 默认假设源文件以 UTF-8 编码；你可以用 source_encoding 配置值来改变它。
陷阱¶
在编写 reST 文档时，通常会遇到一些问题：
行内标记的分离 ：如上所述，行内标记跨度必须通过非单词字符与周围文本分开，您必须使用反斜杠转义空格来绕过它。有关详细信息，请参阅 the reference。
没有嵌套的行内标记 ：像
*see :func:`foo`*这样的东西是不可能的。
脚注
- 1
当默认域包含
class指令时，该指令将被遮蔽。因此，Sphinx 将其重新输出为rst-class。
注释¶
每个不是有效标记结构的显式标记块（如上面的脚注）都被视为注释（ref）。例如
.. This is a comment.您可以在注释开始后缩进文本以形成多行注释