reStructuredText简明教程

作者:刘斗 redfork@gmail.com

图形化 web 编辑工具： rst.ninjs.org

段落

REST 是松散的文本结构，使用预定义的模式描述文章的结构。首先学习最基本的结构：段落。

段落是被空行分割的文字片段，左侧必须对齐（没有空格，或者有相同多的空格）。

缩进的段落被视为引文。

继续缩进……

恢复

恢复

文字样式

最简单的样式是 斜体 和 粗体.

  • *斜体*. 被*包围的文字是斜体
  • **粗体**. 被**包围的文字是粗体

注意: * 两侧必须留有空格, 英文标点符号. 输入法设置为英文标点, 并使用正确的英文标点规范 (逗号, 句号后留一个空格, 引号, 括号两侧留一个空格).

列表

有三种列表:

  1. 顺序,
  2. 公告牌,
  3. 定义.

列表前后, 以及条目之间必须有空行隔开. 列表下面可以插入任意的内容, 段落, 图片都可以, 只要他们的左侧和列表的第一个文字左对齐.

顺序列表

  1. 1. 第 **一** 条
  3.    段落
  5. #. 第二条
  7.    1. 小条
  9. #. 第三条

顺序列表 生成:

  1. 第 一 条

    段落

  2. 第二条

    1. 小条
  3. 第三条

第二条开始后续的条目用 # 开头

顺序列表 - 序号

第一条的序号不必从 1 开始:

  1. 3. 第三条
  3. #. 第四条
  5. 7. 重新设定序号
  7. #. 继续

顺序列表 - 序号 生成:

  1. 第三条

  2. 第四条

  3. 重新设定序号

  4. 继续

顺序列表 - 符号样式

符号:

  1. 1. 数字
  3. a. 小写字母
  5. A. 大写字母
  7. i) 小写罗马数字
  9. (I) 大写罗马数字

顺序列表 - 符号样式 效果

符号:

  1. 数字

  2. 小写字母

  3. 大写字母

  4. 小写罗马数字

  5. 大写罗马数字

公告牌列表

和顺序列表相似, 使用 “*” “+” “-” 代替数字:

  1. * 列表第一级
  3.   + 第二级
  5.     - 第三级
  7.   + 第二级的另一个项目

公告牌列表 生成:

  • 列表第一级
    • 第二级
      • 第三级
    • 第二级的另一个项目

定义列表

或者叫名词解释更确切:

  1. *鸡*
  2.   两条腿, 直立行走, 带翅膀, 有头冠的动物.
  4. *鸭*
  5.   鸡的崇拜者

定义列表生成:

鸡

两条腿, 直立行走, 带翅膀, 有头冠的动物.

鸭

鸡的崇拜者

嵌入程序代码

如果需要嵌入大段的程序代码(SQL, 业务逻辑设置, 配置文件等), 在段落末尾添加两个’:’. 代码的左侧必须缩进, 代码引用到没有缩进的行为止. 例如:

  1. 如果数据库有问题, 执行下面的 SQL::
  3.  # Dumping data for table `item_table`
  5.  INSERT INTO item_table VALUES (
  6.    0000000001, 0, 'Manual', '', '0.18.0',
  7.    '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].',
  8.    '', 1, 1, 20030811192655);

嵌入程序代码生成:

如果数据库有问题, 执行下面的 SQL:

  1. # Dumping data for table `item_table`
  2. INSERT INTO item_table VALUES (
  3.   0000000001, 0, 'Manual', '', '0.18.0',
  4.   '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].',
  5.   '', 1, 1, 20030811192655);

嵌入程序代码 续

如果没有合适的段落添加 ::, 也可以在一个空行上添加, 这个双冒号行被忽略:

  1. ::
  3. #
  4. # Dumping data for table `item_table`
  5. #
  7. INSERT INTO item_table VALUES (
  8.   0000000001, 0, 'Manual', '', '0.18.0',
  9.   '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].',
  10.   '', 1, 1, 20030811192655);

嵌入程序代码 续 生成:

  1. #
  2. # Dumping data for table `item_table`
  3. #
  5. INSERT INTO item_table VALUES (
  6.   0000000001, 0, 'Manual', '', '0.18.0',
  7.   '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].',
  8.   '', 1, 1, 20030811192655);

程序引用体例

可以 用 code-block:: 追加各种语法高亮声明:

  1. .. code-block:: python
  2.     :linenos:
  4.     def foo():
  5.         print "Love Python, Love FreeDome"
  6.         print "E文标点,.0123456789,中文标点,. "

效果:

  1. 1
  2. 2
  3. 3
  1. def foo():
  2.     print “Love Python, Love FreeDome”
  3.     print “E文标点,.0123456789,中文标点,. “

外部包含:

  1. .. literalinclude:: example.py
  2.     :language: python

效果:

  1. #!/usr/bin/env python
  2. #coding:utf-8
  4. print "Hello"

章节

章节是文章的主体结构, 分为 标题 章 节 小节 等. 定义章节的方式是在行的下面添加 ‘=======’, 比如:

  1. 标题
  2. ====
  4. 章
  5. --
  7. 节
  8. ~~
  10. 小节
  11. ####

说明 [1]:

  1. ‘====’ 至少和文字行一样长, 更长也行
  2. 相同级别必须使用统一的符号, 否则会被识别为更小的级别
  3. \= - ~ ` : ‘ ” ^ _ * _ # < > 这些符号都可以, 级别足够多了.
[1]由于幻灯片系统的限制, 效果无法在幻灯片内演示

标题

标题和章节在结构上的作用相同, 但是可能有不同的显示格式. 标题的区别是在章节的上方也加上 ‘====’ 行:

  1. ====
  2. 标题
  3. ====
  5. -----------
  6. 第一章 概述
  7. -----------

表格

普通表格

  1. +------------+------------+-----------+
  2. | Header 1   | Header 2   | Header 3  |
  3. +============+============+===========+
  4. | body row 1 | column 2   | column 3  |
  5. +------------+------------+-----------+
  6. | body row 2 | Cells may span columns.|
  7. +------------+------------+-----------+
  8. | body row 3 | Cells may  | - Cells   |
  9. +------------+ span rows. | - contain |
  10. | body row 4 |            | - blocks. |
  11. +------------+------------+-----------+

普通表格 生成:

Header 1Header 2Header 3
body row 1column 2column 3
body row 2Cells may span columns.
body row 3Cells may span rows.
  • Cells
  • contain
  • blocks.
body row 4

简单表格

注意: 表格包含中文时,基本无法对齐,,,

  1. =====  =====  ======
  2.    Inputs     Output
  3. ------------  ------
  4.   A      B    A or B
  5. =====  =====  ======
  6. False  False  False
  7. True   False  True
  8. False  True   True
  9. True   True   True
  10. =====  =====  ======

简单表格 生成:

InputsOutput
ABA or B
FalseFalseFalse
TrueFalseTrue
FalseTrueTrue
TrueTrueTrue

CSV 表格

  1. .. csv-table:: Frozen Delights!
  2.  :header: "Treat", "Quantity", "Description"
  3.  :widths: 15, 10, 30
  5.  "Albatross", 2.99, "On a stick!"
  6.  "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
  7.  crunchy, now would it?"
  8.  "Gannet Ripple", 1.99, "On a stick!"

CSV 表格生成:

Frozen Delights!
TreatQuantityDescription
Albatross2.99On a stick!
Crunchy Frog1.49If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple1.99On a stick!

列表表格

  1. .. list-table:: Frozen Delights!
  2.   :widths: 15 10 30
  3.   :header-rows: 1
  5.   * - Treat
  6.     - Quantity
  7.     - Description
  8.   * - Albatross
  9.     - 2.99
  10.     - On a stick!
  11.   * - Crunchy Frog
  12.     - 1.49
  13.     - If we took the bones out, it wouldn't be
  14.       crunchy, now would it?
  15.   * - Gannet Ripple
  16.     - 1.99
  17.     - On a stick!

列表表格 生成:

Frozen Delights!
TreatQuantityDescription
Albatross2.99On a stick!
Crunchy Frog1.49If we took the bones out, it wouldn’t be crunchy, now would it?
Gannet Ripple1.99On a stick!

rST排版技巧

跨章节指引

  • 行文中,经常要对其它章节进行指引,在 html 中对应的就是 锚点链接

  • rST 中提供了非常优雅的解决:

    • 使用通用元素定义
    • 比如説:
  1. 各个章节的首页一般是 index.rst
  2. 头一行,习惯性加个聲明:
  3. .. _chapter6index:
  5. 那么,在其它任意文本中,随时可以使用:
  6. :ref:`构建 buzz <chapter6index>`
  7. 来生成一个指向第二章 首页的链接!

插图/表格指代

  • 行文中,经常对指定插图/表格 进行指代

  • rST 中提供了非常优雅的解决:

    • 进行通用元素定义
    • 比如说
  1. .. _fig_0601:
  2. .. figure:: ../_static/figs/magic-2.png
  4.    插图 6-1 神奇的2

然后,就可以在任意地方使用 插图 6-1 神奇的2 来指代, 实际输出的就是 “插图 6-1 神奇的2”

../_images/magic-2.png

插图 6-1 神奇的2

上下标号

有时要进行数学/化学的表示,在 html 中就需要上/下标( <sub> , <sup>) 的表达, rST 中当然也有:

  1. H\ :sub:`2`\ O
  2. E = mc\ :sup:`2`

效果:

H2O

E = mc2

注解

注意:

这里的 只是为了制造语法空间,输出时,是没有空格的了,,,

段落层次约定

使用

  1. 共分4级
  2. =======================
  3. 大标题
  4. =======================
  7. -----------------------
  8. 小标题
  9. -----------------------
  12. ^^^^^^^^^^^^^^^^^^^^^^^
  13. 二级标题
  14. ^^^^^^^^^^^^^^^^^^^^^^^
  17. """""""""""""""""""""""
  18. 三级标题
  19. """""""""""""""""""""""

再小，就使用列表!:

  • 列表项目1
  • 列表项目2
  • …