rst 语法+简明教程

reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。
reStructuredText入门

reStructuredText简明教程

一、行内样式
单星号： text 强调 (斜体),
双星号： text 重点强调 (粗体)，以及
反引号： ``text`` 代码示例。

1. 子体
斜体: * ss *
粗体: ** ssss **
等宽 `` 行内文本(inline literal)通常显示为等宽文本，空格可以保留，但是换行不可以 ``

2. 章节标题
章节头部由下线(也可有上线)和包含标点的标题 组合创建, 其中下线要至少等于标准文本的长度。
可以表示标题的符号有 =、-、`、:、’、"、~、^、_ 、* 、+、 #、<、> 。
对于相同的符号，有上标是一级标题，没有上标是二级标题。
标题最多分六级，可以自由组合使用。
全加上上标或者是全不加上标，使用不同的 6 个符号的标题依次排列，则会依次生成的标题为H1-H6。
=========
一级标题
=========
二级标题
=========

一级标题
^^^^^^^^
二级标题
---------
三级标题
>>>>>>>>>
四级标题
:::::::::
五级标题
'''''''''
六级标题
""""""""
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
3.段落
段落是被空行分割的文字片段，左侧必须对齐（没有空格，或者有相同多的空格）。
缩进的段落被视为引文。

4. 列表
4.1 符号列表(Bullet Lists)
符号列表可以使用 -、 *、+ 来表示。
不同的符号结尾需要加上空行，下级列表需要有空格缩进。

- 符号列表1
- 符号列表2

  + 二级符号列表1

  - 二级符号列表2

  * 二级符号列表3

* 符号列表3

+ 符号列表4
1
2
3
4
5
6
7
8
9
10
11
12
4.2 枚举(顺序)列表(Enumerated Lists)
枚举列表算即顺序(序号)列表，可以使用不同的枚举序号来表示列表。

可以使用的枚举有：

阿拉伯数字: 1, 2, 3, ... (无上限)。
大写字母: A-Z。
小写字母: a-z。
大写罗马数字: I, II, III, IV, ..., MMMMCMXCIX (4999)。
小写罗马数字: i, ii, iii, iv, ..., mmmmcmxcix (4999)。

可以为序号添加前缀和后缀，下面的是被允许的。
. 后缀: "1.", "A.", "a.", "I.", "i."。
() 包起来: "(1)", "(A)", "(a)", "(I)", "(i)"。
) 后缀: "1)", "A)", "a)", "I)", "i)"。
枚举列表可以结合 # 自动生成枚举序号。
1. 枚举列表1
#. 枚举列表2
#. 枚举列表3

(I) 枚举列表1
(#) 枚举列表2
(#) 枚举列表3

A) 枚举列表1
#) 枚举列表2
#) 枚举列表3

枚举列表1
枚举列表2
枚举列表3

I. 枚举列表1
II. 枚举列表2
III. 枚举列表3
A. 枚举列表1
B. 枚举列表2
C. 枚举列表3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
4.3 定义列表(Definition Lists)
定义列表可以理解为解释列表，即名词解释。
条目占一行，解释文本要有缩进；多层可根据缩进实现。

定义1
 这是定义1的内容

定义2
 这是定义2的内容

定义1
这是定义1的内容  

定义2
这是定义2的内容
1
2
3
4
5
6
7
8
9
10
11
4.4 字段列表(Field Lists)
:标题: reStructuredText语法说明

:作者:
 - Seay
 - Seay1
 - Seay2

:时间: 2016年06月21日

:概述: 这是一篇
 关于reStructuredText

 语法说明。

标题: reStructuredText语法说明
作者:

Seay
Seay1
Seay2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
4.5 选项列表(Option Lists)
选项列表是一个类似两列的表格，左边是参数，右边是描述信息。当参数选项过长时，参数选项和描述信息各占一行。
选项与参数之间有一个空格，参数选项与描述信息之间至少有两个空格。

-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
2
3
4
5
6
7
二、超链接
1. 超链接
介绍各类带有链接性质的超链接

1.1 自动超链接
reStructuredText会自动将网址生成超链接。

https://github.com/SeayXu/
1
https://github.com/SeayXu/

1.2 外部超链接(External Hyperlink)
引用/参考(reference)，是简单的形式，只能是一个词语，引用的文字不能带有空格。
这篇文章来自我的Github,请参考 reference_。

.. _reference: https://mp.csdn.net/mdeditor/100424467
1
引用/参考(reference)，行内形式，引用的文字可以带有空格或者符号。
这篇文章来自我的Github,请参考

`mayun<https://mp.csdn.net/mdeditor/100424467>`_。
1
这篇文章来自我的Github,请参考 mayun。

1.3 内部超链接|锚点(Internal Hyperlink)
更多信息参考 引用文档_

这里是其他内容

.. _引用文档:

这是引用部分的内容
1
2
3
4
5
6
7
更多信息参考 引用文档
这里是其他内容

这是引用部分的内容
1.4匿名超链接(Anonymous hyperlink)
词组(短语)引用/参考(phrase reference)，引用的文字可以带有空格或者符号，需要使用反引号引起来。

这篇文章参考的是：`Quick reStructuredText`__。
.. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html
1
2
这篇文章来自我的Github,请参考 Quick reStructuredText。

1.5 间接超链接(Indirect Hyperlink)
间接超链接是基于匿名链接的基础上的，就是将匿名链接地址换成了外部引用名_。

SeayXu_ 是 `我的 GitHub 用户名`__。

.. _SeayXu: https://github.com/SeayXu/

__ SeayXu_
1
2
3
4
5
SeayXu 是 我的 GitHub 用户名。

1.6 隐式超链接(Implicit Hyperlink)
小节标题、脚注和引用参考会自动生成超链接地址，使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。

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

其他内容...

隐式链接到 `第一节 介绍`_，即可生成超链接。

<h6 id="id2">第一节 介绍</h6>
其他内容...
隐式链接到 第一节 介绍，即可生成超链接。
1
2
3
4
5
6
7
8
9
10
2. 替换引用(Substitution Reference)
替换引用就是用定义的指令替换对应的文字或图片，和内置指令(inline directives)类似。

|build| |docs| |license|
.. |build| image:: https://travis-ci.org/googlecartographer/cartographer_ros.svg?branch=master
    :alt: Build Status
    :scale: 100%
    :target: https://travis-ci.org/googlecartographer/cartographer_ros
1
2
3
4
5
3.脚注引用(Footnote Reference)
可以使用 [#name]_ 标注在脚注的位置，在文档的最后的 … rubric:: Footnotes 后添加脚注的内容，像这样:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
1
2
3
4
5
6
脚注引用，有这几个方式：有手工序号(标记序号123之类)、自动序号(填入#号会自动填充序号)、自动符号(填入*会自动生成符号)。

手工序号可以和#结合使用，会自动延续手工的序号。

#表示的方法可以在后面加上一个名称，这个名称就会生成一个链接。

脚注引用一 [1]_
脚注引用二 [#]_
脚注引用三 [#链接]_
脚注引用四 [*]_
脚注引用五 [*]_
脚注引用六 [*]_

.. [1] 脚注内容一
.. [2] 脚注内容二
.. [#] 脚注内容三
.. [#链接] 脚注内容四 链接_
.. [*] 脚注内容五
.. [*] 脚注内容六
.. [*] 脚注内容七

脚注引用一 [1]<a id="id9"></a>
脚注引用二 [3]<a id="id10"></a>
脚注引用三 [4]<a id="id11"></a>
脚注引用四 [*]<a id="id12"></a>
脚注引用五 [†]<a id="id13"></a>
脚注引用六 [‡]<a id="id14"></a>
[1]<a id="id3"></a> 脚注内容一
[2]  脚注内容二
[3]<a id="id4"></a> 脚注内容三
[4]<a id="id5"></a> 脚注内容四 链接  
[*]<a id="id6"></a> 脚注内容五
[†]<a id="id7"></a> 脚注内容六
[‡]<a id="id8"></a> 脚注内容七
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
3. 嵌入程序代码+注释
注释以 … 开头，后面接注释内容即可，可以是多行内容，多行时每行开头要加一个空格。

..
 我是注释内容
 你们看不到我
1
2
3
3.1 嵌入式代码
如果需要嵌入大段的程序代码(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);
1
2
3
4
5
6
7
8
如果没有合适的段落添加 ::, 也可以在一个空行上添加, 这个双冒号行被忽略:
::

#
# 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);
1
2
3
4
5
6
7
8
9
10
可以 用 code-block:: 追加各种语法高亮声明:
.. code-block:: python
    :linenos:

    def foo():
        print "Love Python, Love FreeDome"
        print "E文标点,.0123456789,中文标点,. "

1
2
3
4
5
6
7
4. 表格
普通表格

+------------+------------+-----------+
| 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. |
+------------+------------+-----------+
1
2
3
4
5
6
7
8
9
10
11
简单表格
注意: 表格包含中文时,基本无法对齐,

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======
1
2
3
4
5
6
7
8
9
10
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!"
1
2
3
4
5
6
7
8
列表表格

.. 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!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
5 排版
5.1跨章节指引
行文中,经常要对其它章节进行指引,在 html 中对应的就是 锚点链接
rST 中提供了非常优雅的解决:
使用通用元素定义
比如説:

各个章节的首页一般是 index.rst
头一行,习惯性加个聲明:
.. _chapter6index:

那么,在其它任意文本中,随时可以使用:
:ref:`构建 buzz <chapter6index>`
来生成一个指向第二章 首页的链接!
1
2
3
4
5
6
7
5.2插图/表格指代
行文中,经常对指定插图/表格 进行指代
rST 中提供了非常优雅的解决:
进行通用元素定义
比如说

.. _fig_0601:
.. figure:: ../_static/figs/magic-2.png

   插图 6-1 神奇的2
1
2
3
4
然后,就可以在任意地方使用 插图 6-1 神奇的2 来指代, 实际输出的就是 “插图 6-1 神奇的2”
————————————————
版权声明：本文为CSDN博主「xiaoma_bk」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/xiaoma_bk/article/details/100424467