reStructuredText 简明教程

段落

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

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

缩进的段落被视为引文。

继续缩进……

恢复

恢复

文字样式

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

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

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

列表

有三种列表:

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

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

顺序列表

  1. 1. **一**
  2. 段落
  3. #. 第二条
  4. 1. 小条
  5. #. 第三条

顺序列表 生成:

段落

  1. 第二条

    1. 小条
    2. 第三条

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

顺序列表 - 序号

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

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

顺序列表 - 序号 生成:

  1. 第三条
  2. 第四条
  3. 重新设定序号
  4. 继续

顺序列表 - 符号样式

符号:

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

顺序列表 - 符号样式 效果

符号:

  1. 数字
  2. 小写字母
  3. 大写字母
  4. 小写罗马数字
  5. 大写罗马数字

公告牌列表

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

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

公告牌列表 生成:

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

定义列表

或者叫名词解释更确切:

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

定义列表生成:

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

嵌入程序代码

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

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

嵌入程序代码 续 生成:

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

程序引用体例

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

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

效果:

  1. 1
  2. 2
  3. 3
  4. def foo():
  5. print "Love Python, Love FreeDome"
  6. print "E文标点,.0123456789,中文标点,. "

外部包含:

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

效果:

  1. @route('%s/'%ini.urlprefix)
  2. def index():
  3. __urlog("INFO","idx++")
  4. return template('index.tpl',urlprefix=ini.urlprefix)

章节

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

  1. 标题
  2. ====
  3. --
  4. ~~
  5. 小节
  6. ####

说明 [1]:

  1. ‘====’ 至少和文字行一样长, 更长也行
  2. 相同级别必须使用统一的符号, 否则会被识别为更小的级别
  3. = - ~ ` : ‘ ” ^ * # < > 这些符号都可以, 级别足够多了.

[1] 由于幻灯片系统的限制, 效果无法在幻灯片内演示

标题

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

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

表格

普通表格

  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 1 column 2 column 3

body row 2 Cells may span columns.

body row 3 Cells 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

False False False

True False True

False True True

True True True

CSV 表格

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

CSV 表格生成:

Frozen Delights!

TreatQuantityDescription

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

列表表格 生成:

Frozen Delights!

TreatQuantityDescription

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!

rST排版技巧

跨章节指引

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

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

    • 使用通用元素定义
    • 比如説:

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

那么,在其它任意文本中,随时可以使用: :ref:构建 buzz <chapter6index> 来生成一个指向第二章 首页的链接!

插图/表格指代

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

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

    • 进行通用元素定义
    • 比如说

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

插图 6-1 神奇的2

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

_images/magic-2.png

插图 6-1 神奇的2

上下标号

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

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

效果:

H2O

E = mc2

Note

注意:

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

段落层次约定

使用 reSTsections_

  1. 共分4
  2. =======================
  3. 大标题
  4. =======================
  5. -----------------------
  6. 小标题
  7. -----------------------
  8. ^^^^^^^^^^^^^^^^^^^^^^^
  9. 二级标题
  10. ^^^^^^^^^^^^^^^^^^^^^^^
  11. """""""""""""""""""""""
  12. 三级标题
  13. """""""""""""""""""""""

再小,就使用列表!:

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

推荐文章