其实之前写过一篇 关于 AsciiDoc 的博文,其中提到过 reStructuredText ,最近赋闲,有朋友问了我关于 reStructuredText 的问题,于是也就有了写这篇语法入门的念头。

什么是 reStructuredText

简单说,reStructuredText 也是一种轻量级的文本标记语言,字面意思是 重构建的文本,是 PythonDocutils 项目的一部分,这也是为什么之前我一直说用 reStructuredText 感觉在写 Python 的原因。

reStructuredText 其一般保存的文件以 .rst 为后缀,必要时可以被转换为成 PDFHTML 等格式,也可以由 Sphinx 转化为 LaTexman 等格式,在程序文档撰写方面应用也比较广泛。

编辑器

至于编辑器,依旧推荐你使用 Atom,记得搜索和安装相关的插件即可。

如果找不到适合你的 Atom 插件或编辑器,你也可以尝试 在线编辑器 (如果你喜欢的话,它是 开源 的)。

与其他格式的转换

通常你可能希望将你的 .rst 文件转换为 .html.pdf 等格式,推荐几个工具吧:

  • Pandoc,对于我这样的懒人直接 brew install pandoc

  • rst2html5,用 pip install rst2html5 就好了

  • rst2pdf,同上,用 pip

  • rst2epub,同上,用 pip

  • rst2pptx,同上,用 pip

嗯,的确很 Python 吧。


标题(Title)

===================
这就是一个标题
===================
----------------
这也是一个标题
----------------

支持用来修饰标题符号有:

!、"、#、$、%、&、'、(、)、*、+、,、-、.、/、:、;、<、=、>、?、@、[、\、]、^、_、`、{、|、}、~

其中,官方推荐使用的有:

=、-、`、:、.、’、"、~、^、_、*、+、#

通常并没有对标题的层级指定明确的标线字符,但对于 Pyhton 文档,可以使用如下约定:

  • #: 有上标线, 用以部分
  • *: 有上标线, 用以章节
  • =: 用以小节
  • -: 用以子节
  • ^: 用以子节的子节
  • " 用以段落

如果你仍旧觉得复杂,你也可以只给出下半部分:

这个标题和上面的一样
===================

作为修饰的字符长度要大于等于文字长度。此外,标题是可以嵌套的。

段落(Paragraphs)

段落是一段左对齐且没有其他元素体标记的文字,通过空行与其他内容分隔。

当段落带有缩进时,将被解析为引用段落,样式方面会有不同。

这是一个段落,一个可以很长的段落,直到空行


这是另一个段落,与前面的段落用空行分割

    这仍旧是一个段落,但由于带有缩进,会被解析为引用段落。

样式 (Style)

基本的文字样式有:

  • 斜体 (Italic): 使用 * 包围,例如 ` some word ,注意两端需要留有空格,HTML 中一般用 ` 表示

  • 粗体 (Strong): 使用 ** 包围,例如 ` some word ,注意两端需要留有空格,HTML 中一般用 ` 表示

  • 等宽字体 (Monospace): 使用 `` 包围,例如 ``Inline Literals``HTML 中一般用 <tt> 表示

  • 引用 (Interpreted Text): 使用 ` 包围,例如 `Interpreted Text`HTML 中一般用 <cite> 表示

  • 外部链接 (External Links)

`Link text <https://example.com/>`_ 来记录行内链接. 如果文字本身就是链接, 那不用作任何标记,解析器可以自动将链接和邮箱地址转换为超链接。

也可以单独定义链接目标用引用,比如:

This is a paragraph that contains `a link`_.

.. _a link: https://example.com/
  • 内部链接 (Internal Links)

Sphinx 使用特殊 reST 规则支持内部链接, 请参考 详细定义规则

图片 (Images)

.. image:: gnu.png
   (options)

图片尺寸的解释选项 (widthheight) 有如下规约:

如果大小没给任何单位或单位是像素, 输出通道优先使用像素(换言之,非 LaTeX 输出). 其他单位(如 pt 或是 点) 将被用于 HTMLLaTeX 输出.

Sphinx 扩展了标准 docutils 行为,支持如下的星号指代:

.. image:: gnu.*

脚注 (Footnotes)

脚注使用 [#name]_ 来标记位置, 并在文章底部 “Footnotes” 专栏之后追加脚注内容:

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

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

你也可以使用确切编号的脚注 (如: [1]_) 或是自动编号 ([#]_)。

引证 (Citations)

标准 reST 支持引证,有额外的功能是 “global”, 也就是说引证能从所有文件来引用。

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

引证的使用基本和脚注相同, 不过使用的标签不是数字或是以 # 开始.

替换 (Substitutions)

替换以 |name| 形式来定义替换的文本或是标记对象,如脚注,可以在直解标记文本块中声明,形如:

.. |name| replace:: replacement *text*

或是:

.. |caution| image:: warning.png
             :alt: Warning!

注释 (Comments)

.. This is a comment.

可以用缩进文本来进行多行注释:

..
   This whole indented block
   is a comment.

   Still in the comment.

上下标

HTML<sub><sup> 标签,常用于数学、化学、商标等。使用 \ :sub: `上标内容`\\ :sup: `下标内容`\ 表示

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

列表(List)

reStructuredText,列表分为:

  • 有序列表 (Enumerated Lists)

  • 无序列表 (Bullet Lists)

  • 定义列表 (Definition Lists),与 HTML 中的 dl 标签相同

  • 字段列表 (Field Lists)

  • 选项列表 (Option Lists)

列表是可以嵌套的。

无序列表

无序列表采用符号 *+- 中任意一个作为开头,紧跟空格,后加列表项内容。对于不同的层级,拥有不同长度的缩进。

- 第一级的第一个列表项

- 第一级的第二个

- 第一级的第三个

  - 缩进的列表第一个列表项
    缩进要与当前列表项的缩进同步

- 第一级的第四个

有序列表

无无序列表类似,区别在于开头的符号必须是可排序的字符,常见的有:

  • 阿拉伯数字: 1, 2, 3, …

  • 大写英文字母: A, B, C, …, Z

  • 小写英文字母: a, b, c, …, z.

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

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

为了方便撰写,你也可以只标明第一个列表项的序号,后面使用 #reStructuredText 自动生成需要的序号 (Docutils >= 0.3.8)。

1. 第一项
    一些内容...

#. 第二项

    a. 第二项的第一小项

    #. 第二项的第二小项

#. 第三项
a. 小写字母

A. 大写字母

i) 小写罗马数字

(I) 大写罗马数字

定义列表

前面说过了,定义列表与 HTMLdl 标签一样。

定义列表的列表项,包含:

  • 术语 (term): 一行文字或者短语

  • 分类器 (classifiers)(可选): 跟在术语后,用 ` : ` (空格,冒号,空格)分隔

  • 定义(definition): 相对于术语缩进后的块,可以包含多个段落或者其他的内容元素

术语和定义之间可以没有空行,但在定义列表前后必须有空行

术语1
    术语1的定义

术语 2
    术语2的定义第一段

    术语2的定义第二段

术语 3 : 分类器
    术语3的定义


术语 4 : 分类器1 : 分类器2
    术语4的定义

字段列表

选项列表

表格 (Table)

reStructuredText 支持的表格有:

  • 网格表格 (Grid Tables)

  • 简单表格 (Simple Tables)

  • CSV表格 (CSV Tables)

  • 列表表格 (List Tables)

网格表格

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

其中:

  • -: 分隔行

  • =: 分隔表头和表体行

  • |: 分隔列

  • +: 用来表示行和列相交的节点

表头行是可选的,如果你不需要,就可以不用 = 来分割了。

简单表格

这种表格简单许多,一般用于简单的数据展示。用于修饰简单表格的符号也只有 =-

  • 基本形式,最简单的表格形式,当然你也可以去掉表头展示
=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
  • 表内嵌入,下面这种简单表内有列表
=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====
  • 表头合并,表头进行分类合并
=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False A
True   False  True
False  True   True
True   True   True
=====  =====  ======

TIPS:列需要和”=”左对齐,不然可能会导致出错;如果碰到第一列为空时,需要使用”"来转义,不然会被视为是上一行的延续;网格表和简单表中,简单表比较适合展现简单的数据,这些数据本身不需要太复杂的展现形式,而一旦碰到需要和并单元格这类的复杂操作,可能网格表会更加适合。

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

列表表格

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

块 (Blocks)

块在 reStructuredText 中的表现方式有:

  • 文字块 (Literal Blocks)

  • 引用文字块 (Quoted Literal Blocks)

  • 线块 (Line Blocks)

  • 文本测试块 (Doctest Blocks)

块的表达非常简单,在前面内容结束之后,使用两个冒号 :: 紧跟空行的方式来分割,后面接入块的内容,块内容要相对之前的内容有缩进。

普通文字块:

这里是块之前的的内容 ::

   这里是块的内容。前面有缩进、空行和分隔符。
    此处内容会被一直视为块内容

    块内容可以包含空行

当不再和块内容一样缩进时,自动结束
下面是我们的测试代码:

::

    for i in [1,2,3,4,5]:
        print i
    # 代码块测试

很简单的代码块测试。

线块:

| These lines are
| broken exactly like in
| the source file.

对于代码,还可以加入高亮:

.. code-block:: python
    ::

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

文件包含:

.. literalinclude:: example.py
    :language: python