reStructuredtext快速入门
reStructuredText是一种reStructuredText是一种轻量级的文本标记语言，简单易读，所见即所得的文本标记语言。
其一般保存的文件以.rst为后缀。在必要的时候，.rst文件可以被转化成PDF或者HTML格式，也可以有Sphinx转化为LaTex,man等格式，现在被广泛的用于程序的文档撰写。
段落
段落是reST文档中最基础的部分，段落通过一个或者多个空行分隔开。左侧必须对齐（没有空格，或者有相同多的空格）。
内联标记
标准的reST内联标记包括：粗体、斜体以及引用。
- *text*：使用一个星号包裹文本表示斜体
- **text**：使用两个星号包裹文本表示粗体
- ``text``：使用两个反引号包裹文本表示
代码块
如果星号或反引号出现在文本会对行内标记分隔符引起混淆，他们必须用一个反斜杠进行转义。
标记需注意的一些限制:
- 不能相互嵌套
- 内容前后不能有空白: 这样写
* text*是错误的, - 如果内容需要特殊字符分隔. 使用反斜杠转义，如:
this is\ *one*\ word
这些限制在未来版本可能会被改善.
列表与引用
顺序列表
1. 第 **一** 条
段落
#. 第二条
1. 小条
#. 第三条第二条开始后续的条目用 # 开头。第一条的序号不必从 1 开始。
顺序列表包括如下符号样式：
1. 数字
a. 小写字母
A. 大写字母
i) 小写罗马数字
(I) 大写罗马数字列表前后, 以及条目之间必须有空行隔开. 列表下面可以插入任意的内容, 段落, 图片都可以, 只要他们的左侧和列表的第一个文字左对齐。
无序列表
和顺序列表相似, 使用 “*” “+” “-” 代替数字:
* 列表第一级
+ 第二级
- 第三级
+ 第二级的另一个项目自定义列表
或者叫名词解释更确切:
*鸡*
两条腿, 直立行走, 带翅膀, 有头冠的动物.
*鸭*
鸡的崇拜者嵌入程序代码
如果需要嵌入大段的程序代码(SQL, 业务逻辑设置, 配置文件等), 在段落末尾添加两个’:’， 并且代码块需要与周围文本以空行分隔，代码的左侧必须缩进, 代码引用到没有缩进的行为止. 例如:
如果数据库有问题, 执行下面的 SQL::
# Dumping data for table `item_table`
INSERT INTO item_table VALUES (
0000000001, 0, 'Manual', '', '0.18.0',
'This is the manual for Mantis version 0.18.0.\r\n\r\nThe Mantis manual is modeled after the [url=http://www.php.net/manual/en/]PHP Manual[/url]. It is authored via the \\"manual\\" module in Mantis CVS. You can always view/download the latest version of this manual from [url=http://mantisbt.sourceforge.net/manual/]here[/url].',
'', 1, 1, 20030811192655);高亮代码
可以 用 .. code-block:: 追加各种语法高亮声明:
.. code-block:: python
:linenos:
def foo():
print "Love Python, Love FreeDome"
print "E文标点,.0123456789,中文标点,. "引用外部代码：
.. literalinclude:: example.py
:language: python表格
普通表格
+------------+------------+-----------+
| 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. |
+------------+------------+-----------+简单表格
有一些限制,需要有多行，且第一列元素不能分行显示，如下:：
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======CSV表格
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"列表表格
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!超链接
外部链接
使用 链接文本 <http://example.com/>_ 可以插入网页链接。 链接文本是网址，则不需要特别标记，分析器会自动发现文本里的链接或邮件地址。
可以把链接和标签分开, 如下:
段落里包含 `a link`_.
.. _a link: http://example.com/内部链接
章节
章节是文章的主体结构, 分为 标题 章 节 小节 等. 定义章节的方式是在行的下面添加 ‘=======’, 比如:
标题
====
章
--
节
~~
小节
####通常没有专门的符号表示标题的等级，但是对于Python 文档，可以这样认为:
# 及上划线表示部分
* 及上划线表示章节
=, 小章节
-, 子章节
^, 子章节的子章节
", 段落显示标记
显式标用在那些需做特殊处理的reST结构中, 如尾注，突出段落，评论，通用指令.
显式标记以 .. 开始，后跟空白符，与下面段落的缩进一样. (在显示标记与正常的段落间需有空行，这听起来有些复杂，但是写起来会非常直观.)
指令
指令是显式标记最常用的模块。也是reST 的扩展规则, 在 Sphinx 经常被用到。
图像
reST 支持图像指令, 如下
.. image:: gnu.png
(选项)这里给出的文件名( gnu.png) 必须是源文件的相对路径，如果是绝对路径则以源目录为根目录. 例如，在文件 sketch/spam.rst 引用图像 images/spam.png ，则使用 ../images/spam.png 或者 /images/spam.png.
Sphinx 会自动将图像文件拷贝到输出目录的子目录里，( 输出HTML时目录为 _static )
注释
有明确标记块但又不是有效的结构标记的标记 (像上面的尾注）都被视为注释，例如:
.. 这是一个评论.可以通过缩进产生多行注释:
..
这整个缩进块都是
一个评论.
仍是一个评论.