reStructuredText入门

python文档规范学习

2016-08-22 632 words 3 minutes views

Contents

reStructuredText入门

什么是reStructuredText?

reStructuredText通常简称为RST,ReST,reST,是Python里面最为常见的文档格式，他跟Markdown一样，语法在很多地方也很类似，如果有过Markdown的写作经验，入门reStructuredText是一件非常容易的事情。

RST规范

如果你本地没有即时浏览的编辑器，强烈推荐通过Online Editor来快速上手，我们的介绍几乎都是从官方文档移植过来的。目的是便于个人整理和回顾，个人学习还是推荐去官方文档查看。

文本

加粗和斜体

RST中的加粗和斜体跟Markdown中用法一致都是通过*和**来指定的:

1
2


*this is italics*
**this is bold**

替代文本(interpreted text)

一般配合rst中的描述标记使用，用来做链接，引用，解释等,例如站外链接:

1

please contact email `<http://username.organisze.org/>`_

Embedded hyperlink

内嵌的外部链接，引用和定义放在一起

1
2
3
4
5


`display_text link_address`_ :在引用符中间就是具体的显示字符和链接地址，后面紧跟_,  
#以下面实际的例子对比Markdown:  

External hyperlinks, like `Python <http://www.python.org/>`_.  RST  
External hyperlinks, like [Python](http://www.python.org/).  Markdown  

Hyperlink target

引用和定义分开，可以多次引用，使用_建立对应关系，可用于纸质输出文档，他的效果和我们上面最终的效果一致:

1
2
3


External hyperlinks, like Python_.  

.. _Python: http://www.python.org/  

Inline hyperlink

引用文章内部的区域,就类似于url里面的#,语法跟外部target引用一样，只是定义的时候需要使用如下的格式:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# 其实就是在定义的时候生成一个带id的div，到时候再通过#指向该区域而已
External hyperlinks, like Python2_.  

.. _Python2:  

this is python2 content  

#RST生成的title默认就带有id，所以可以直接引用title  

Title link :`This is title`_.  

This is title  
=============    

图片引用

简单的图片插入可以使用**::image**,具体参照如下:

1
2


     For instance:
     .. image:: images/ball1.gif (这里支持相对和绝对路径)  

如果需要在inline中使用png图标，可以配合使用||:

1
2
3


     The |biohazard| symbol must be used on containers used to dispose of medical waste.

     .. |biohazard| image:: biohazard.png

页脚注释引用

可以使用[index]_:

1
2
3


    Footnote references, like [5]_.

    .. [5] A numerical footnote. Note

多个引用支持配置自增长,#是基于已有的footage列表做累加，遇到已有的定义会自动跳过

1
2
3
4
5
6


    Footnote references, like footage_1 [#]_.
    Footnote references, like footage_2 [#]_.

    .. [1] this is footage 1
    .. [#] This is the first one.    actual 2
    .. [#] This is the second one.   actual 3

引证

引证的用法跟页脚注释引用一致:

1
2
3
4
5
6
7


  Citation references, like [CIT2002]_.
  Note that citations may get
  rearranged, e.g., to the bottom of
  the "page".

  .. [CIT2002] A citation
     (as often used in journals).

段落和其他

标题

标题是通过在文字的下面或者上下面增加一行特殊字符表示，字符的长度不能短于文字的长度，可供选择的字符有:= - : ' " ~ ^ _ * + # < >, 比如:

1
2
3
4
5


  =====
  Title
  =====
  Subtitle
  --------

虽然RST本身没有规定层级标题的用法，但是python对不同级别的标题还是有建议规范:

1. \# with overline, for parts
2. \* with overline, for chapters
3. =, for sections
4. -, for subsections
5. ^, for subsubsections
6. ", for paragraphs

段落

段落不需要缩进，但是新的段落需要空行，如一下面所示:

1
2
3


  This is a paragraph.

  This is another paragraph

无序列表

RST中的无序列表跟markdown很像，支持多个不同的符号- * +,符号和内容之前需要有空格:

1
2
3
4
5


  This is a list

  - item1
  - item2
  - item3

有序列表

RST中的有序列表支持使用**#**作为自增长符号:

1
2
3
4
5
6


  This is sequenced list:

  1. item1
  2. item2
  3. item3
  #. item4

定义列表

定义列表在python的documentation中很常见，需要注意的是在定义的内容中需要缩进，不同的内容之间需要有空行:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


  Definition lists:

  what
    Definition lists associate a term with
    a definition.

  how
    The term is a one-line phrase, and the
    definition is one or more paragraphs or
    body elements, indented relative to the
    term. Blank lines are not allowed
    between term and definition.

字段列表

字段列表在form和brief中比较常见，格式跟定义列表很像，区别在于需要以**:**开头:

1
2
3
4
5
6
7


  :Authors:
      Tony J. (Tibs) Ibbs,
      David Goodger
      (and sundry other good-natured folks)

  :Version: 1.0 of 2001/08/08
  :Dedication: To my father.

命令选项列表

这个能帮我们快速构建命令行参数文档，需要注意的是在描述和参数中间至少需要两个空格:

1
2
3
4
5
6
7


  -a            command-line option "a"
  -b file       options can have arguments
                and long descriptions
  --long        options can be long also
  --input=file  long options can also have
                arguments
  /V            DOS/VMS-style options too

Literal Blocks(Quota Blocks)

这个跟我们的引用区域很像，通过查看生成的html源代码可以看到literal blocks会生成**<pre>标记，而我们的引用区域是直接生成<blockquota>标签这个也能方便我们理解他的作用,一般通过::**来标记开始，内容区域需要使用缩进:

1
2
3
4
5
6
7


  content below is literal Blocks::

    this is content

    this is also content

  this is another paragraph

或者通过**>**来表示:

1
2
3


  content below is literal Blocks::

  > this is content

表格

表格的格式如下,跟markdown一样都比较清晰，自己写文档的时候可以直接借助工具生成，不需要手动编辑,在这里推荐Table Generator,不过他目前只是简单支持:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


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

过渡

即我们html常见的<hr>,一般用的很少，在视觉上隔开段落:

1
2
3
4
5
6
7
8
9


  A transition marker is a horizontal line
  of 4 or more repeated punctuation
  characters.

  ------------

  A transition should not begin or end a
  section or document, nor should two
  transitions be immediately adjacent.

RST文件预览(windows环境)

跟markdown一样，在编写文档的时候，我们也需要能够本地即时预览，在这一点上Sublimetext和他强大的plugin再合适不过了，这里推荐OmniMarkupPreviewer，大部分的markup语言都支持:

Markdown
reStruecturedText
Textile
Pod
RDoc
Org Mode
MediaWiki
AsciiDoc
Literate Haskell
WikiCreole

插件支持实时预览,浏览器预览快捷键(Ctrl+Alt+O)