本节简要介绍了reStructuredText (reST)的概念和语法，旨在提供足够的信息来高效地编写文档。因为reST是一个简单的，不显眼的标记语言，这不会花费太长时间来入门。
See also
权威的 reStructuredText用户文档。
注：因为找不到合适的词语来翻译role，所以没有翻译！
标准的行内标记相当简单：使用
如果星号或反引号出现在文本会对行内标记分隔符引起混淆，他们必须用一个反斜杠进行转义。
注意行内标记一些限制:
docutils以后的版本可能会取消上列出的这些限制。
reST也允许自定义“文本解释role”，这就意味着所包含的文本应以一种特定的方式解释。Sphinx用它提供了语义标记和交叉引用的标识符。一般的语法格式是 :rolename:`content` 。
标准的reST提供了如下些roles：
Sphinx添加的roles请见 Inline markup。
列表标记(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.
请注意，term 不能有一个以上的文本行。
引用段落(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:”。
Sphinx支持两种表格形式。对于 格子表格 (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
===== ===== =======
使用 `Link text <http://example.com/>`_ 来实现内嵌的网页链接。如果链接文本是Web地址，你一点都不需要特殊标记，解析器可以识别在普通的文本的链接和邮件地址。
你也可以把链接和目标定义(ref)分开，像这样:
This is a paragraph that contains `a link`_.
.. _a link: http://example.com/
内部链接是通过Sphinx提供的一个特殊的reST role来实现的，请看 Cross-referencing arbitrary locations.
章节头 (ref) 是用特殊的标点符作为章节标题的下划线来创建的（上划线是可选的），只要文字:
=================
This is a heading
=================
通常，没有特定的字符指定给标题级别，因为结构是用从继承的标题来确定的。对于python文档，本公约您可以按照：
当然，您可以自由使用自己的标记字符（参看reST文档），并使用一个更深层次的嵌套级别，但请记住，大多数的目标格式（HTML，LaTeX）有限地支持嵌套深度。
“显式标记” (ref) 在reST中是用于需要进行特殊处理的结构，比如脚注，特别突出的段落，注释，和通用指令（标识符）。
显式标记块的第一行是以 .. 开始，接着是紧随着空格，被结束于同样层级缩进的下一段落。（显式标记和正常的段落之间需要有一个空行。当你写它的时候，可能听起来有点复杂，但它是直观的。）
指令或者标识符（ref）是一个通用的显式标记块。除了roles，指令或者标识符是reST的扩展机制，Sphinx大量地使用了它。
Docutils支持如下的指令（标识符）：
请 不要 使用指令（标识符） sectnum， header 以及 footer。
Sphinx自己增加的指令（标识符）是在 Sphinx标记结构 中描述的。
基本上，指令（标识符）由一个名称，参数，选项和内容组成。（请记住这些术语，它被用来在接下来的章节描述了自定义指令或者标识符。）请看例子，:
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function 是指令（标识符）的名称。在这里它有两个参数，第一行其余的部分以及第二行，还有一个选项 module （正如可以看到的，选项是在参数的下一行以及以冒号开始以冒号结束）。选项必须跟指令的内容缩进到相同的水平。
指令（标识符）的内容与选项之间空一行，需要相对于指令（标识符）的首行缩进（以指令的首行为缩进的对照点）。
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）的解释如下：如果大小没有单位或单位是像素，那图片大小将会被那些支持像素的输出格式关心（LaTeX格式就不在乎这种情况的图片大小）。HTML和LaTeX输出格式使用其他的单位（像 pt 表示像素点）。
Sphinx扩展了标准的docutils的功能，允许文件扩展名为星号:
.. image:: gnu.*
Sphinx搜索所有的图片匹配提供的模式，并确定其类型。每个生成器会从所有的候选者中选择最佳的图片。比如，如果给出 gnu.* 这样的文件名以及源代码树中存在 gnu.pdf 和 gnu.png 这两个文件，LaTeX 生成器会选择前者，HTML生成器则会选择后者。
Changed in version 0.4: 增加了支持以星号结尾的文件名。
Changed in version 0.6: 图片的路径可以是绝对的。
可以使用 [#name]_ 标注在脚注的位置，在文档的最后的 .. rubric:: Footnotes 后添加脚注的内容，像这样:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
你也可以明确用数字标注脚注或者通过不指定 name 使用自动数字标记脚注([#]_)。
Sphinx支持标准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 或把它们放到一个单独的文件，要使用它们的所有文件中包含它，通过使用 include 指令或者标识符。（务必使得include文件扩展名与其他的源文件不同，以免让Sphinx把它作为一个独立的文件。）
Sphinx自定义了一些默认的替换, 请看 Substitutions。
不是一个有效的标记结构（如上述的脚注）的每一个明确的标记块被视为一条评论（ref）。例如:
.. This is a comment.
您可以缩进文本在注释开始后，这样可以形成多行注释:
..
This whole indented block
is a comment.
Still in the comment.
由于包括特殊字符如在reST中的破折号或版权标志，最简单的方法是直接写为Unicode字符，指定编码。Sphinx假定源文件默认情况下是使用UTF-8编码；你可以改变 source_encoding 这一配置值。
这有些问题通常发生在编写reST文档的时候：
Footnotes
| [1] | 当默认域包含一个 class 指令（标识符），该指令将被隐藏。因此，Sphinx将它转为 rst-class。 |