reStructuredText在线编辑器 http://rst.ninjs.org/

ReST是Docutils的标记语法,Docutils是Python世界的文档工具集。也因为这样ReST在Python界中被广泛应用,比如Sphinx–这个基于Docutils的文档工具–事实上作为Python中的标准文档工具被广泛使用了。比如Python官方文档。因为Sphinx可以生成多种格式,

设计思路对比
—————

先来看一下 Markdown ,

官方的说法直截了当, Markdown 就是个 text-to-HTML 的工具。

所以说,从一开始,Markdown 就确立了它与 HTML 的亲缘性。这是 Markdown 的设计立足点。

Markdown 包含两个部分,

1. 文本结构化格式,也就是标记语言

2. 另外与之配套的生成 HTML 的 perl 程序。

作为标记语言, Markdown 的目标很明确,就是为了更简单的写 html 。

相比与 Markdown , reST 显然是经过精心设计的。

reST 的目标是,建立一套标准文本结构化格式用以将文档转化为有用的数据格式。

不得不说的是这句话一点都不 Pythonic ,和政治书上的句子似的。

所以 Pythoner 给出了更具体的阐述:

按重要程度依次罗列:

1. Readable,是可阅读的,reST的原文本必须可以很容易的直接阅读而不需要了解reST的标记语法。

2. Unobtrusive,不突兀的,reST 所使用的标记应该是尽量简单并且不突兀的。越是常用的标记越应该简单和不碍眼的。不太常用的标记,或者是表达特殊意义的标记应该鲜明。

3. Unambiguous,没有歧义的,标记规则是确定的,不能再重载定义,对于给定的一个输入,只有一个可能的输出,包括输出错误。

4. Unsurprising,不出乎预期的,非“魔法”的,标记语言可以不输出不想输出的内容。所以,需要一个方式(标记)作为标记不期望输出标记之用。比如,当你想要向别人展示reST源代码时,你要标记这块reST源码不需要被结构化。

5. Intuitive, 直观的,标签应该尽可能的容易被记住。人们可以在文档中直接使用。

6. Easy,简单,

通过一段时间的使用,我觉得 Markdown 和 reST 都可以说达到了他们的既定目标。

进过一段时间的使用,我觉得 reST 基本达到了预定的目标。

权衡的艺术
~~~~~~~~~~~

通过以上的比较,我们发现, reST 承载的目标要比 Markdown 多很多。最重要的不同就在于 Markdown 只是为了输出 HTML ,而 reST 的目标之一就是可以转化为其他格式。

当然,说权衡是艺术,还不如说其实就是瞎子摸象弄出一些聊以自慰的藉口罢了。

不过从已经获取到的相关信息,我们可以初步做一个判断,用 Markdown 作为中心书写工具(一般是配合 Pandoc )相对于使用 reST 做中心书写工具是不佳的。何况,又引入了新的工具( Pandoc )和语言( Haskell ),这都是非必要的正熵,背离了 KISS 原则。

说了这么多其实就一句话:

我们选择标记语言实际上是在表意与简便之间做权衡,我们的理想目标是即表意丰富又使用简便。

但是,这个世界上鱼和熊掌得兼的事情不多,往往我们只能根据自己的需要去寻找一个最优平衡点来决策。

 

转自:http://ieqi.net/2012/04/13/markdown-%E8%BF%98%E6%98%AF-restructuredtext/

两者对比:

https://github.com/windfire-cd/note/blob/master/rst_mkd/rst_mkd.rst

 

ReSt文档标题:

========
文档标题
========

----------
文档副标题
----------
文档标题和副标题通常用在封面页

章节

Section Header
==============
Subsection Header
-----------------

three sub 三级标题
``````````````
这些是文档各节(section)的标题,文档的目录根据这些标题生成。

标题
可以使用字母数字以外的可打印ACSII字符,官方推荐的是以下字符:

Recommended choices are
"``= - ` : ' " ~ ^ _ * + # < >``"
标题前后的符号数目必须大于等于标题的长度


段落
段落的格式:

段落不需要特殊标记,用空行来分割,
段落内的换行是被忽略的,因此源文件
可以很好地控制一行的长度。

这是一段。

这是第二段。

   段落可以缩进,通常用来表达引用的文字

 

行内标记
用来实现斜体、粗体、引用、脚注、引用等等:

*斜体*, **粗体**, hyperlink_, 脚注 [3]_

.. [3] 脚注的正文
.. _hyperlink: http://jerrypeng.me
还有更多其他标记,请参考文档

Markdown和reStructuredText语法比较

Markdown和reStructuredText语法比较

1. 数字和点开始有序列表。

   1. 注意子列表的缩进位置。

      1. 三级列表。
      1. 编号会自动更正。

   1. 二级列表,编号自动更正为2。

2. 返回一级列表。

 

列表中,相同的层级使用相同的缩进。

列表中同一层级不需要空行分隔。不同层级起始处必须有空行

独立链接 ,自动将网址转换为链接。

例如 http://www.ubuntu.org.cn/

http://www.ubuntu.org.cn/
 

命名链接 ,为链接命名,有助记忆和减少空间占用。

在正文中使用 <链接名>_ ,注释中使用 _<链接名>: [链接目标]

例如 Ubuntu

Ubuntu_

.. _Ubuntu:  http://www.ubuntu.org.cn/

表格
表格的格式:

 

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

Markdown和reStructuredText语法比较

 

简单表格的格式:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

 

Markdown和reStructuredText语法比较


指令(Directives)
指令是基本的标记之外的扩展机制

有一组标准的指令
目录
图片,内嵌代码
公式
标准指令大全 [4]
不同的工具可以实现自己独特的指令以实现高级功能

[4] http://docutils.sourceforge.net/docs/ref/rst/directives.html

 

  • 指令的格式如下:

    .. directive_type:: directive
       block

嵌入图片:

.. image:: funny.gif
   :height: 100px
   :width: 100px
   :alt: funny cat picture
   :align: center

嵌入代码:

 

.. code:: python

    def say_hello():
        print 'Hello, ReST'

    if __name__ == '__main__':
        say_hello()

docutils-0.9才开始支持,无法演示了……

sphinx和rst2pdf支持code-block这个指令
用法和上面的一致,把code改成code-block即可。

sphinx对嵌入程序代码的支持很好(本来就是为了编写python文档而开发的工具)。

在段落的结尾添加符号 :: ,则表明下面的段落为代码段落。代码段落相对之前的段落要缩进一次。

普通文本段落,下一段是代码段落::

    缩进结束前
        代码段落不会被处理

 普通文本段落

文本

只要没有空行,不管换多少次行,都会处理为一行。 建议您将每行的内容控制在50个汉字或者100个字母之内, 尽量在标点符号处手动换行,以增加源文件的可读性。


上面的例子转自可爱的rst:
http://wiki.jerrypeng.me/rest-tjlug/

http://www.worldhello.net/gotgithub/appendix/markups.html
http://jwch.sdut.edu.cn/book/tool/UseSphinx.html

分类:

技术点:

相关文章: