1. 概念
reStructuredText 是一种轻量级的文本标记语言，是 Python 中 Docutils 项目的一部分。其文件以 .rst 为后缀。在必要的时候，可以被转化成 PDF 或者 HTML 格式，也可以由 Sphinx 转化为 LaTex、man 等格式，现在被广泛的用于程序的文档撰写。
之前已经使用过一种标记型语言 Markdown。官方的说法直截了当， Markdown 就是个 text-to-HTML 的工具，为了更简单的写 html 而生。与之相比，reST 的目标是建立一套标准文本结构化格式用以将文档转化为有用的数据格式。
2. 语法
2.1 段落
段落类似 md 中的语块，是 reST 文件的基本模块。段落是由空行分隔的一段文本。
和 Python 一样, 对齐也是 reST 的操作符, 因此同一段落的行都是左对齐的。 如果段落相较于其他的段落有缩进，reST 会解析为引用段落，样式上有些不同。
2.2 标题
标题在上下双划线符号之间, 并且符号的长度不能小于文本的长度（.rst文件中可以只给出下半部分的字符）:
=================
This is a heading
=================
This is another heading
-----------------------
任意一个非字母数字字符都可用作标题的划线符号，如下：
= - ` : ' " ~ ^ _ * + # < >
对于相同的符号，有上标是一级标题，没有上标是二级标题。通常没有专门的符号表示标题的等级，但是对于 Python 文档，可以这样认为:
#及上划线表示部分*及上划线表示章节=小章节-子章节^子章节的子章节"段落
当然也可以用标记定义标题的层次，但是需要注意输出格式（HTML, LaTeX）所支持的层次深度。
2.3 行内样式
标准的 reST 行内样式相当简单:
- 星号: text 是强调 （斜体）
- 双星号: text 重点强调 （加粗）
- 反引号:
text代码样式，等宽字体，空格会保留，但换行符不会
星号及反引号在文本中容易与内联标记符号混淆，可使用反斜杠符号转义。
2.4 列表
2.4.1 无序列表
无序列表以-、*或+加一个空格起始，第一项与最后一项之前需要空行与其它段落分开，各项之间空行则非必须。示例：
- This is item 1
- This is item 2
2.4.2 有序列表
有序列表以数字、单个字母或罗马字符加一个.和空格起始。序号即是最终呈现的列表序号，因此需要有序排列并且不必一定从 1 开始。另外，可使用#延续之前的格式自动产生一个递增序号。示例：
3. This is the first item
4. This is the second item
#. This item is auto-enumerated
2.4.3 其它列表
-
概念列表
一般用于阐述特定术语的。示例：
what Definition lists associate a term with a definition. how The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition. -
字段列表
字段列表被用作扩展语法的一部分，例如类数据库记录以待后续进一步处理，或文档中的通用两列表结构。示例
:Authors: Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) :Version: 1.0 of 2001/08/08 :Dedication: To my father. -
选项列表
常见于软件工具的说明文档，示例：
-a command-line option "a" -b file options can have arguments and long descriptions --long options can be long also --input=file long options can also have arguments /V DOS/VMS-style options too需注意，选项及其说明之间需要间隔两个空格以上。
2.5 表格
2.5.1 网格表
示例：
+------------+------------+-----------+
| Header 1 | Header 2 | Header 3 |
+============+============+===========+
| body row 1 | column 2 | column 3 |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
| body row 4 | | - blocks. |
+------------+------------+-----------+
= 用来分隔表头和表体行，表头会加粗显示。
2.5.2 简单表
示例：
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
列需要和=左对齐，不然可能会导致出错。如果碰到第一列为空，需要使用\来转义，不然会被视为是上一行的延续。
2.4 显式标记 Explicit Markup
2.4.1 注脚 Footnotes
每个注脚由明确的开始标记..，左方括号，注脚标签，右方括号和空格组成，后跟缩进的主体元素。 注脚标签可以是：
- 一个十进制数字
- 一个
#（表示自动编号的脚注） - 一个
#后跟一个简单的参考名称（一个自动编号标签） - 一个
*（表示自动符号脚注）
示例：
Footnote references, like [5]_. Note that footnotes may get
rearranged, e.g., to the bottom of the "page".
.. [5] A numerical footnote. Note there's no colon after the ``]``.
2.4.2 引文 Citations
引文和注脚类似，区别只是标签使用由字母、数字、连字符、句点或下划线构成的文本，不含空格，字母不区分大小写。
示例：
Citation references, like [CIT2002]_. Note that citations may get
rearranged, e.g., to the bottom of the "page".
.. [CIT2002] A citation (as often used in journals).
2.4.3 超链接 Hyperlink Targets
超链接可定位到文档内或文档外的一处位置。可分为具名和不具名两类，语法分别为：
.. _hyperlink-name: link-block
.. __: anonymous-hyperlink-target-link-block
or
__ anonymous-hyperlink-target-link-block
超链接目标按其位置可分为三类：
-
内部超链接目标
link-block 为空，后跟正文段落。其它位置点击超链接可以快速定位到该正文部分。 是文档内交叉引用的方法。
示例：
Clicking on this internal hyperlink will take us to the target_below. .. _target: The hyperlink target above points to this paragraph. -
外部超链接目标
link-block 是 URI 或邮箱地址。示例：
See the Python_ home page for info. `Write to me`_ with your questions. .. _Python: http://www.python.org .. _Write to me: jdoe@example.com -
间接超链接目标
link-block 是一个 hyperlink-name_。示例：
.. _one: two_ .. _two: three_ .. _three:
2.4.4 指令 Directives
指令是一种通用的扩展机制，是一种在不添加新语法的情况下添加对新构造的支持的方式。通用语法如下：
.. directive-type:: directive-block
directive-block 可以由参数、选项（字段列表）、说明文字构成。
给出几个指令的常用场景：
2.4.4.1 告警
官方支持的告警关键字包括attention、cautio、dange、erro、hin、importan、not、ti、warning。示例：
.. DANGER::
Beware killer rabbits!
上述示例可能被解析为如下图表：
+------------------------+
| !DANGER! |
| |
| Beware killer rabbits! |
+------------------------+
2.4.4.2 图片
语法：
.. image:: image-URI
图片还以字段列表的格式支持一些格式修订：
-
class : text
设定 “classes” 属性。
-
name : text
设定 “names” 属性。可在超链接中用作图片的别名。
-
alt : text
图片的简要描述，某些应用在图片不能显示时显示该描述。
-
height : length
图片的理想高度。
-
width : length or percentage of the current line width
图片宽度。
-
scale : integer percentage （”%”符号非必需）
缩放比例，默认为100 %。
-
align : “top”, “middle”, “bottom”, “left”, “center”, or “right”
对齐方式。其中”top”, “middle”, “bottom”是行内图片与行文本的垂直对齐方式；”left”, “center”, “right”控制水平对齐方式，允许文字环绕图片。
-
target : text （URI 网址或 reST 超链接）
将图片作为超链接，点击可定位到指定位置。
示例：
.. image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right
2.4.4.3 代码段
示例：
.. code:: python
:number-lines: 1
def my_function():
"just a test"
print 8/2
指定语言后，解析器会使用 Pygments 做语法高亮。
2.4.4.4 数学表达式
支持LaTeX格式的数学表达式，示例：
.. math::
α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)
2.4.4.5 文本替换
示例：
I recommend you try |Python|_.
.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
reST 支持当前本地时间的替换，示例：
.. |date| date::
.. |time| date:: %H:%M
Today's date is |date|.
This document was generated on |date| at |time|.
2.4.5 注释
以显式标记（两个句点..）开始又不满足特定语法的都是注释，解析器不会将其在正文中显示出来。示例：
.. This text will not be shown
(but, for instance, in HTML might be
rendered as an HTML comment)