reStructuredText入门¶
本节简要介绍reStructuredText（reST）的概念和语法，旨在为作者提供足够的信息来有效地创作文档。由于reST被设计为一种简单、不唐突的标记语言，这不会花太长时间。
另请参见
权威的reStructuredText用户文档。本文档中的“ref”链接链接到reST参考中各个结构的描述。
内联标记¶
标准的reST内联标记很简单：使用
- 一个星号：
*text*表示强调（斜体）， - 两个星号：
**text**表示强烈的强调（粗体），和 - 反引号：
``text``表示代码示例。
如果星号或反引号出现在正在运行的文本中，并且可能与内联标记分隔符混淆，则必须使用反斜杠对其进行转义。
请注意此标记的一些限制：
- 它不可以嵌套，
- 内容不能以空格开头或结尾：
* text*是错误的， - 它必须通过非字符字符与周围文本分开。使用反斜杠转义空格避开这个问题：
thisis\ *one*\ word。
这些限制可能会在docutils的未来版本中取消。
reST还允许自定义“可解释的文本角色”，它表示应以特定方式解释围起来的文本。Sphinx使用它来提供语义标记和标识符的交叉引用，在适当的小节有所描述。一般的语法是:rolename:`content`。
标准reST提供以下角色：
- emphasis –
*emphasis*的替代拼写 - strong –
**strong**的替代拼写 - literal –
``literal``的替代拼写 - subscript – 下标文字
- superscript – 上标文字
- title-reference – 用于书籍、期刊和其他资料的标题
有关Sphinx添加的角色，请参阅内联标记。
类似列表和引用的文本块¶
列表标记（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:”。
表格¶
支持两种形式的表格。对于网格表格（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
===== ===== =======
超链接¶
Sections¶
章节标题（ref）通过使用符号字符在章节标题下方（上方也可以有）创建，其至少与文本一样长：
=================
This is a heading
=================
通常，没有为特定字符分配标题级别，因为结构是从标题的序列中确定的。但是，下面这个约定用在Python文档风格指南中，你可以遵循：
#，用在上方表示部分*，用在上方表示章=，表示节-，表示子节^，表示子节的子节"，表示段落
当然，你可以自由使用你自己的标记字符（参见reST文档），并使用更深的嵌套级别，但请记住，大多数目标格式（HTML，LaTeX）支持的嵌套深度都有限。
显式的标记¶
“显式的标记”（ref）在reST中用于大多数需要特殊处理的结构（例如脚注、特别突出显示的段落、注释和通用指令）。
显式的标记块以..开头的行开始，后面跟着空格，并以相同缩进级别的下一个段落结束。（在显式的标记和正常段落之间需要有一个空白行。这可能听起来有点复杂，但当你书写它的时候是很直观的。）
指令¶
指令（ref）是显式的标记的通用块。它是reST除了角色之外的扩展机制之一，Sphinx大量使用它。
Docutils支持以下指令：
警告：attention、caution、danger、error、hint、important、note、tip、warning和通用的admonition。（大多数主题风格只有“note”和“warning”。）
图片：
其他body元素：
- contents (a local, i.e. for the current file only, table of contents)
- container（具有自定义类的容器，用于生成一个HTML格式的外围
<div>） - rubric（与文档分段无关的标题）
- topic，sidebar（特殊突出显示的主体元素）
- parsed-literal（支持内联标记的文字块）
- epigraph（带可选属性行的引用块）
- highlights，pull-quote（带有自己的类属性的引用块）
- compound（复合段落）
特殊的表格：
- table（带标题的表格）
- csv-table（以逗号分隔的值生成的表格）
- list-table（从系列列表生成的表格）
特殊指令：
特定于HTML的：
影响标记：
- default-role（设置新的默认角色）
- 角色（创建新角色）
因为这些只是每个文件，请更好地使用Sphinx的工具来设置
default_role。
Sphinx添加的指令在Sphinx标记的结构中有所描述。
基本上，指令由名称、参数、选项和内容组成。（记住这个术语，它在下一章描述自定义指令时使用。）看这个例子，
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function是指令名称。它在这里给出两个参数，第一行和第二行的其余部分，以及一个选项module（如你所见，选项在紧接着参数的行中给出，并由冒号指出）。选项必须缩进到与指令内容相同的级别。
指令内容在空行之后，并相对于指令的开始缩进。
Images¶
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]_来标记脚注的位置，并在文档的底部“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*
or this:
.. |caution| image:: warning.png
:alt: Warning!
有关详细信息，请参阅替换的reST参考。
如果你想对所有文档使用一些替换，请将它们放在rst_prolog中，或将它们放入单独的文件中，并使用include指令将其包含到你要使用它们的所有文档中。（确保为include文件提供与其他源文件不同的文件扩展名，以避免Sphinx将其作为独立文档找到）。
Sphinx定义了一些默认替换，参见替换。
注释¶
每个非有效标记结构（如上述脚注）的显式标记块被视为注释（ref）。例如：
.. This is a comment.
你可以在注释开始后缩进文本以形成多行注释：
..
This whole indented block
is a comment.
Still in the comment.
源文件的编码¶
由于在reST中包含特殊字符（如em dash或版权符号）的最简单方法是直接将它们写为Unicode字符，因此必须指定编码。默认情况下，Sphinx假定源文件以UTF-8编码；你可以使用source_encoding配置值更改它。