3. 简单语法介绍¶
3.1. 段落¶
段落是最基础的文本块, 每个段落是由紧挨在一起的一行或多行文字构成，段落之间使用一个或者多个空行隔开（好的习惯是使用一个就够了）。 段落可以缩进，但是同一个段落的行必须和第一行保持同样的缩进。
段落样例:
我是一个单行段落
这是第二个段落，
着同样属于第二个段落
这是第三个段落了
这是第四个单行段落
上面就是段落的案例，渲染出来就是像下面一样
我是一个单行段落
这是第二个段落， 着同样属于第二个段落
这是第三个段落了
这是第四个单行段落
3.2. 行内元素¶
行内元素是指单行内，针对某些字加一些样式，比如 *倾斜*和**加粗**， 如果希望倾斜的同时加上一个类似于边框的效果，可以使用``框内的内容``。
如果*在里面，比如``*``，会当做内容。并且， reStructuredText 非常智能，大多数情况下会自动判断你的*是不是需要被解释为加粗或者倾斜。 比如 5*6=30 , 如果发现 reStructuredText 解释错了，可以使用 \* 强制让它 解释为内容。
渲染出来如下
- 倾斜
- 加粗
带框的倾斜
3.3. 列表¶
列表分为三种： 有序列表、无序列表、定义。
每个列表项可以包含多行、多个段落，并且可以列表之间无限嵌套。如果需要嵌套一个列表，只要子列表增加缩进就可以了。
每次新建一个列表，需要开始一个新的段落 – 意思就是，列表之前必须有一个空行。
3.3.1. 有序列表¶
有序列表可以使用 阿拉伯数字、罗马数字、字母加上 . 或者 ) 作为开头，不过两个都加上也可以，还可以把内容用()括起来，当然其他形式的任意组合也是可以的。
举例:
A. 我是列表
B. 我也是列表
a. 我是子列表
i. 罗马数字的子列表
这句写到第二行
ii. 罗马数字的子列表
1). 我是另一个列表
这个列表项还有第二个段落。
(1). 又是一个新列表
渲染后是下面的样子。
- 我是列表
- 我也是列表
- 我是子列表
- 罗马数字的子列表 这句写到第二行
- 罗马数字的子列表
1). 我是另一个列表
这个列表项还有第二个段落。
(1). 又是一个新列表
如果不想每次都写上编号，有一个偷懒的办法：第一项写上序号，后面的使用#。
a. 这是第一项
#. 这是第二项
#. 这是第三项
渲染如下:
- 这是第一项
- 这是第二项
- 这是第三项
3.3.2. 无序列表¶
无序列表和有序列表差不多，也可以支持多行、多段落、无限嵌套。 不同的是，无序列表只需要前面加一个特殊字符就可以了，可以选择 “-“, “+” 或者 “*”。
举例:
* 这是一个无序列表
- 这是子列表
+ 嵌套的子列表
这是第二段
- 还是子列表
渲染出来如下：
- 这是一个无序列表
- 这是子列表
嵌套的子列表
这是第二段
还是子列表
3.3.3. 定义¶
和上面两种有点不一样，这种形式通常用来定义一些比较复杂的东西。
举例:
ps
用来查看Linux系统进程快照的shell命令。
**top**
用来查看进程实时状态的命令。
可以交互式操作。
渲染出来如下:
- ps
- 用来查看Linux系统进程快照的shell命令。
- top
用来查看进程实时状态的命令。
可以交互式操作。
3.4. 展示原始代码¶
这种形式通常用来定义代码块，和上面列表中的 定义 类似。使用 :: 创建一个标示。代码块中的内容相对于标示需要更多的缩进。 代码块中的内容会原样展示，不会当做 reStructuredText 的格式。标示也可以省略，这样的话就只有代码块。
举例:
列表排序的代码::
content = sorted(content, key=lambda x: x.key)
::
没有标识的代码: [n**2 for n in range(9)]
渲染如下:
列表排序的代码:
content = sorted(content, key=lambda x: x.key)
没有标识的代码: [n**2 for n in range(9)]
3.5. 章节、标题¶
举例:
第一章
===========
第一节
------------
第1.1小节
*****************
第二章
==========
像上面的例子，一行文字下面使用 =、-、* 标记，就可以让那一行称为标题，并且，下面的标记必须比文字长。
另外一个注意的点是，标记符本身并不和标题层级绑定，而是越先出现的级别越高。 上面使用 = 作为一级标题，也可以使用 - 作为一级标题，= 作为二级标题。
可以选择的下标符号有： = - ` : ‘ ” ~ ^ _ * + # < > 。
通常Python实践约定比较规范的操作是:
- # 上下都有, 用于文档的某一部的标题。
- * 上下都有, 用于做某一章的标题。
- =, 用于某一节标题
- -, 用于某一小节标题
- ^, 用于某一小小节标题
- “, 用于段
3.6. 副标题¶
举例:
============
标题
============
----------------
这里有个副标题
----------------
第一章
============
如果希望有副标题，需要使用不同的标题符号来标记副标题，并且正标题上下都需要使用符号包围，且正副标题紧邻在一起，没有空行。
3.7. 图片¶
举例:
.. image:: /images/ape.png
渲染如下:
也可以设置额外属性:
.. image:: /images/ape.png
:height: 100
:width: 200
:scale: 50
:alt: 这是一只大猩猩
效果如下: