• 段落
  • 文字样式
  • 列表
    • 顺序列表
    • 顺序列表 - 序号
    • 顺序列表 - 符号样式
    • 公告牌列表
  • 定义列表
  • 嵌入程序代码
    • 嵌入程序代码 续
    • 程序引用体例
  • 章节
  • 标题
  • 表格
    • 普通表格
    • 简单表格
    • CSV 表格
    • 列表表格
  • rST排版技巧
    • 跨章节指引
    • 插图/表格指代
    • 上下标号
  • 段落层次约定
  • 推荐文章

    reStructuredText 简明教程

    段落

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

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

    缩进的段落被视为引文。

    继续缩进……

    恢复

    恢复

    文字样式

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

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

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

    列表

    有三种列表:

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

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

    顺序列表

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

    顺序列表 生成:

    1. 第 一 条

    段落

    1. 第二条

      1. 小条
      2. 第三条

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

    顺序列表 - 序号

    第一条的序号不必从 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. #
    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);

    嵌入程序代码 续 生成:

    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
    5. def foo():
    6.     print "Love Python, Love FreeDome"
    7.     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. ====
    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 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
    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

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

    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. =======================
    7. -----------------------
    8. 小标题
    9. -----------------------
    12. ^^^^^^^^^^^^^^^^^^^^^^^
    13. 二级标题
    14. ^^^^^^^^^^^^^^^^^^^^^^^
    17. """""""""""""""""""""""
    18. 三级标题
    19. """""""""""""""""""""""

    再小，就使用列表!:

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

    推荐文章

    • 可爱的reStructuredText

    • 轻量级标记语言