reStructuredText 标记

reStructuredText（reST） 是 Sphinx 使用的默认纯文本标记语言。

章节标题

章节标题由下线（或上、下线）标记，其中线长不得小于标准文本的长度。标题最多分六级，使用不同的 6 种符号依次排列，则会依次生成的标题 H1~H6 。

建议标题深度不超过 3 级（H1~H3），标题使用的符号依次是 # * = - . ~ ，长度最小 36 个字符。

H1 一级标题
####################################

H2 二级标题
************************************

H3 三级标题
====================================

段落

段落是由一个或多个空行分隔的文本块，同一段落中的所有行必须保持相同的缩进级别，并且段落与段落之间需要用空行分开。

提示

在 reStructuredText 文件中缩进和空行是区分段落（文字块）的基本方法。

行块

reStructuredText 文件在输出时，会将紧邻的两行合并为一行。行块可以打破这种规则，使每行单独输出。使用行块时以 | 开头，后跟一个空格。

下面是一段行块内容，使用行块的行不会合并：

    | Lend us a couple of bob till Thursday.
    | I'm absolutely skint.
    | Love, Ewan.

这是新的一段。

引用块

引用块是通过缩进来实现的，引用块要在前面的段落基础上缩进。通常引用的结尾会加上出处，出处的文字块以 -- 开头。

下面是引用的内容：

    “真的猛士，敢于直面惨淡的人生，敢于正视淋漓的鲜血。”

    --- 鲁迅

代码块

代码块通常用于展示代码或命令，使用 :: 标记，代码块中的内容会保持原有格式（多行或缩进）。

注意

1. :: 标记后边需紧接一个空行

2. 代码块不能顶头写，要有缩进

下面是一段代码示例：
::

    flag = True

    for i in number_list:
        if i = 89:
            flag = False
            break

这是新的一段。

表格

rst 格式支持两种表格样式，可以构建出完整的自定义表格。

网格表格

网格表格允许任意单元格内容，以及行和列跨度。但是，网格表格生成起来很麻烦，特别是对于简单的数据集。

网格表格是用由字符 - = | + 组成的可视化网格来描述的。 - 用来分隔行， = 用来分隔表头和表体行， | 用来分隔列， + 用来表示行和列相交的节点。

+------------+------------+-----------+
| 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
=====  =====  =======

另外一种混合的样式。

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

列表

列表可以简单的分为有序列表和无序列表。

无序列表

符号列表可以使用 - * + 来表示，二级列表需要缩进。

- 符号列表 1
- 符号列表 2
    - 二级符号列表 1
    - 二级符号列表 2
    - 二级符号列表 3
- 符号列表 3
- 符号列表 4

有序列表

可用的有序列表序号：

• 阿拉伯数字: 1, 2, 3, ... (无上限)。

• 大写字母: A-Z。

• 小写字母: a-z。

• 大写罗马数字: I, II, III, IV, ..., MMMMCMXCIX (4999)。

• 小写罗马数字: i, ii, iii, iv, ..., mmmmcmxcix (4999)。

有序列表支持三种格式，序号后边紧跟空格：

• . 后缀，例如： 1.

• ) 英文右括号后缀，例如： 1)

• () 英文括号包起来，例如： (1)

1. 有序列表 1
2. 有序列表 2
3. 有序列表 3

定义完第一个序号后，可以结合 # 自动生成序号。

1. 有序列表 1.
#. 有序列表 2.
#. 有序列表 3.

字段列表

字段列表类似两列的表格结构。多用于文档信息的记录。

:标题: reStructuredText语法说明
:作者: - Seay
       - Seay1
       - Seay2
:时间: 2016年06月21日
:概述: 这是一篇关于 reStructuredText
       语法说明。

选项列表

选项列表是一个两列的表格，输出类似于 Linux 中使用 man 命令查看命令选项。左边是参数（不能以单词开头），右边是描述信息。

选项与参数之间有一个空格，参数与描述信息之间至少两个空格。

-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

定义列表

定义列表多用于名词解释，条目占一行，解释文本占一行需要缩进。

定义1
   这是定义 1 的内容。

定义2
   这是定义 2 的第 A 项。
   这是定义 2 的第 B 项。

链接

链接也称超级链接，是指从一个网页指向一个目标的连接关系，所指向的目标可以是另一个网页，也可以是相同网页上的不同位置，还可以是图片、电子邮件地址、文件、甚至是应用程序。

自动超链接

reStructuredText 会自动将网址文本的超链接。

这个网址会自动生成链接：https://www.python.org/

外部超链接

外部超链接目标在其链接块中具有链接地址或电子邮件地址。

单词链接示例:
Python_ 是一种高级的程序设计语言。
.. _Python: https://www.python.org/

短语链接示例:
`Python 3.6`_ 包含许多新功能和优化。
.. _`Python 3.6`: https://docs.python.org/3.6/

内嵌链接示例:
`Python <https://www.python.org/>`_ 是一种高级的程序设计语言。

内嵌连接只能用于单文本，而上边两种链接样式可以用于多个文本相同的链接。

内部链接（锚点）

一个内部的链接目标指向目标后面的元素。

更多信息参考 锚点_

这里包含其它文档内容...

.. _锚点:

这是锚点定位的元素

章节超链接

章节超链接只能链接至当前文件的章节标题，类似于内部超链接的一个子集。

如果章节超链接命名和外部超链接有冲突的话，外部超链接会覆盖具有相同引用名称的任何章节超链接。

第一节 介绍
====================================

其他内容...

章节超链接到 `第一节 介绍`_ ，需要和章节名相同。

外部章节超链接

外部章节超链接不是一个官方的用法，只是依据 Sphinx 输出时会为每个标题自动添加 ID 的规则（文件中第一个标题为 id1，以下的内容每出现一个标题 id 号自动加 1。），起到链接到标题的作用。

通过外部超链接的方式链接到外部章节的 id 号。

超链接到 `abc.rst 的第 6 个标题 <abc.html#id6>`_ 。

行内标记

行内标记必须满足以下条件：

• 行内标记开始字符之前和结束字符之后，都必须紧跟空白字符（空格）

• 行内标记开始字符之后和结束字符之前，都必须紧跟非空白字符

• 行内标记字符之间至少包含一个字符

• 行内标记字符之间不能有换行

注意

行内标记不能嵌套使用。

*重点，通常显示为斜体*
`解释文字，通常显示为斜体`
**重点强调，通常显示为粗体**
``行内代码，通常显示为等宽字体``

脚注引用

脚注引用，有几种方式：

• 手工标记序号（标记序号 1、2、3 之类）

• 自动序号（使用 # 自动填充序号），类似于有序列表

当使用 # 自动填充序号时，可以在后面加上一个名称，这个名称会生成一个链接链接至脚注引用。

脚注引用一 [1]_
脚注引用二 [#]_
脚注引用三 [#]_
脚注引用四 [#跳转]_

.. [1] 脚注内容一
.. [#] 脚注内容二
.. [#] 脚注内容三
.. [#跳转] 脚注内容四，点击“跳转”到此

其他的文本内容...

跳转_ 这个链接会跳转到 [#跳转] 脚注上。

分隔符

分隔符是一条水平的横线，相当于 HTML 标签中的 <hr> 标签。由最少 4 个 - 组成，前后需要添加换行。

上面部分

------------

下面部分

注释

注释以 .. 开头，后面接注释内容即可，多行内容时需要缩进。

.. 我是注释内容
   你们看不到我

转义符

reStructuredText 标记语言将一些文本字符（例如： * ` . : ）定义为特殊用途的元字符，定义的元字符将失去文本字符的意义。转义符 \ 就是将元字符转换回文本字符的原有意义。

# 转义 ** 的文本加粗定义
\*\*Python\*\* 是一门很受欢迎的编程语言。

提示

转义符转义自身

由于转义符也是一个元字符，构建文档时，Sphinx 会将转义符解释成特殊用途。在文档中需要使用 \ 字符本意时，需要使用转义符转义自身（即使用 \\ ）