reStructuredText(rst)快速入門語法說明

reStructuredText 是擴展名爲.rst的純文本文件，含義爲"從新構建的文本""，也被簡稱爲：RST或reST；是Python編程語言的Docutils項目的一部分，Python Doc-SIG (Documentation Special Interest Group)。該項目相似於Java的JavaDoc或Perl的POD項目。 Docutils 可以從Python程序中提取註釋和信息，格式化成程序文檔。

.rst 文件是輕量級標記語言的一種，被設計爲容易閱讀和編寫的純文本，而且能夠藉助Docutils這樣的程序進行文檔處理，也能夠轉換爲HTML或PDF等多種格式，或由Sphinx-Doc這樣的程序轉換爲LaTex、man等更多格式。

本文語法來自Quick reStructuredText

因爲格式緣由，以爲這個不是很直觀的話，能夠到個人github上查看。

行內樣式

斜體

重點、解釋文字

*重點(emphasis)一般顯示爲斜體*
`解釋文字(interpreted text)一般顯示爲斜體`

重點(emphasis)一般顯示爲斜體

粗體

重點強調

**重點強調(strong emphasis)一般顯示爲粗體**

重點強調(strong emphasis)一般顯示爲粗體

等寬

``行內文本(inline literal)一般顯示爲等寬文本，空格能夠保留，可是換行不能夠。``

行內文本(inline literal)一般顯示爲等寬文本，空格能夠保留，可是換行不能夠。

章節標題

章節頭部由下線(也可有上線)和包含標點的標題 組合建立, 其中下線要至少等於標準文本的長度。

能夠表示標題的符號有 =、-、`、:、'、"、~、^、_ 、__*__ 、+、 #、<、> 。

對於相同的符號，有上標是一級標題，沒有上標是二級標題。

標題最多分六級，能夠自由組合使用。

全加上上標或者是全不加上標，使用不一樣的 6 個符號的標題依次排列，則會依次生成的標題爲H1-H6。

=========
一級標題
=========
二級標題
=========

一級標題
^^^^^^^^
二級標題
---------
三級標題
>>>>>>>>>
四級標題
:::::::::
五級標題
'''''''''
六級標題
""""""""

一級標題

二級標題

一級標題

二級標題

三級標題

四級標題

五級標題

六級標題

---

段落

段落是被空行分割的文字片斷，左側必須對齊（沒有空格，或者有相同多的空格）。

縮進的段落被視爲引文。

列表

符號列表(Bullet Lists)

符號列表可使用 -、*、+ 來表示。

不一樣的符號結尾須要加上空行，下級列表須要有空格縮進。

- 符號列表1
- 符號列表2

  + 二級符號列表1

  - 二級符號列表2

  * 二級符號列表3

* 符號列表3

+ 符號列表4

• 符號列表1

• 符號列表2

  • 二級符號列表1

  • 二級符號列表2

  • 二級符號列表3

• 符號列表3

• 符號列表4

枚舉(順序)列表(Enumerated Lists)

枚舉列表算即順序(序號)列表，可使用不一樣的枚舉序號來表示列表。

可使用的枚舉有：

• 阿拉伯數字: 1, 2, 3, ... (無上限)。

• 大寫字母: A-Z。

• 小寫字母: a-z。

• 大寫羅馬數字: I, II, III, IV, ..., MMMMCMXCIX (4999)。

• 小寫羅馬數字: i, ii, iii, iv, ..., mmmmcmxcix (4999)。

能夠爲序號添加前綴和後綴，下面的是被容許的。

. 後綴: "1.", "A.", "a.", "I.", "i."。
() 包起來: "(1)", "(A)", "(a)", "(I)", "(i)"。
) 後綴: "1)", "A)", "a)", "I)", "i)"。

枚舉列表能夠結合 # 自動生成枚舉序號。

1. 枚舉列表1
#. 枚舉列表2
#. 枚舉列表3

(I) 枚舉列表1
(#) 枚舉列表2
(#) 枚舉列表3

A) 枚舉列表1
#) 枚舉列表2
#) 枚舉列表3

1. 枚舉列表1

2. 枚舉列表2

3. 枚舉列表3

I. 枚舉列表1
II. 枚舉列表2
III. 枚舉列表3

A. 枚舉列表1
B. 枚舉列表2
C. 枚舉列表3

定義列表(Definition Lists)

定義列表能夠理解爲解釋列表，即名詞解釋。

條目佔一行，解釋文本要有縮進；多層可根據縮進實現。

定義1
 這是定義1的內容

定義2
 這是定義2的內容

定義1

這是定義1的內容

定義2

這是定義2的內容

字段列表(Field Lists)

:標題: reStructuredText語法說明

:做者:
 - Seay
 - Seay1
 - Seay2

:時間: 2016年06月21日

:概述: 這是一篇
 關於reStructuredText

 語法說明。

標題: reStructuredText語法說明
做者:

• Seay

• Seay1

• Seay2

時間: 2016年06月21日
概述: 這是一篇 關於reStructuredText
語法說明。

選項列表(Option Lists)

選項列表是一個相似兩列的表格，左邊是參數，右邊是描述信息。當參數選項過長時，參數選項和描述信息各佔一行。

選項與參數之間有一個空格，參數選項與描述信息之間至少有兩個空格。

-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

參數選項	描述信息
-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

因爲格式問題，這裏只是一個示例，實際上時沒有上面的表頭列和表格豎直線的。

塊(Blocks)

文字塊(Literal Blocks)

文字塊就是一段文字信息，在須要插入文本塊的段落後面加上 ::，接着一個空行，而後就是文字塊了。

文字塊不能定頂頭寫，要有縮進，結束標誌是，新的一段文本貼開頭，即沒有縮進。

下面是文字塊內容：
::

   這是一段文字塊
   一樣也是文字塊
   仍是文字塊

這是新的一段。

下面是文字塊內容：

這是一段文字塊
一樣也是文字塊
仍是文字塊

這是新的一段。

行塊(Line Blocks)

行塊對於地址、詩句以及無裝飾列表是很是有用的。行塊是以 | 開頭，每個行塊能夠是多段文本。

| 先後各有一個空格。

下面是行塊內容：
 | 這是一段行塊內容
 | 這一樣也是行塊內容
   仍是行塊內容

這是新的一段。

下面是行塊內容：

這是一段行塊內容  
這一樣也是行塊內容 仍是行塊內容

這是新的一段。

塊引用(Block Quotes)

塊引用是經過縮進來實現的，引用塊要在前面的段落基礎上縮進。

一般引用結尾會加上出處(attribution)，出處的文字塊開頭是 --、--- 、—，後面加上出處信息。

塊引用可使用空的註釋 .. 分隔上下的塊引用。

注意在新的塊和出處都要添加一個空行。

下面是引用的內容：

    「真的猛士，勇於直面慘淡的人生，勇於正視淋漓的鮮血。」

    --- 魯迅

..

      「人生的意志和勞動將創造奇蹟般的奇蹟。」

      — 涅克拉索

下面是引用的內容：

「真的猛士，勇於直面慘淡的人生，勇於正視淋漓的鮮血。」
—魯迅

「人生的意志和勞動將創造奇蹟般的奇蹟。」
—涅克拉索

文檔測試塊(Doctest Blocks)

文檔測試塊是交互式的Python會話，以 >>> 開始，一個空行結束。

>>> print "This is a doctest block."
This is a doctest block.

>>> print "This is a doctest block."
This is a doctest block.

表格(Tables)

reStructuredText提供兩種表格：網格表（Grid Tables），簡單表（Simple Tables）。

網格表(Grid Tables)

網格表中使用的符號有：-、=、|、+。

- 用來分隔行， = 用來分隔表頭和表體行，| 用來分隔列，+ 用來表示行和列相交的節點。

Grid table:

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

效果請查看:這裏

簡單表(Simple Tables)

簡單表相對於網格表，少了 | 和 + 兩個符號，只用 - 和 = 表示。

Simple table:

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

效果請查看:這裏

分隔符

分隔符就是一條水平的橫線，是由 4 個 - 或者更多組成，須要添加換行。

上面部分

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

下面部分

上面部分

---

下面部分

超連接

介紹各種帶有連接性質的超連接

自動超連接

reStructuredText會自動將網址生成超連接。

https://github.com/SeayXu/

https://github.com/SeayXu/

外部超連接(External Hyperlink)

引用/參考(reference)，是簡單的形式，只能是一個詞語，引用的文字不能帶有空格。

這篇文章來自個人Github,請參考 reference_。

.. _reference: https://github.com/SeayXu/

引用/參考(reference)，行內形式，引用的文字能夠帶有空格或者符號。

這篇文章來自個人Github,請參考 `SeayXu <https://github.com/SeayXu/>`_。

這篇文章來自個人Github,請參考 SeayXu。

內部超連接|錨點(Internal Hyperlink)

更多信息參考 引用文檔_

這裏是其餘內容

.. _引用文檔:

這是引用部分的內容

更多信息參考 引用文檔

這裏是其餘內容

這是引用部分的內容

匿名超連接(Anonymous hyperlink)

詞組(短語)引用/參考(phrase reference)，引用的文字能夠帶有空格或者符號，須要使用反引號引發來。

這篇文章參考的是：`Quick reStructuredText`__。

.. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html

這篇文章來自個人Github,請參考 Quick reStructuredText。

間接超連接(Indirect Hyperlink)

間接超連接是基於匿名連接的基礎上的，就是將匿名連接地址換成了外部引用名_。

SeayXu_ 是 `個人 GitHub 用戶名`__。

.. _SeayXu: https://github.com/SeayXu/

__ SeayXu_

SeayXu 是 個人 GitHub 用戶名。

隱式超連接(Implicit Hyperlink)

小節標題、腳註和引用參考會自動生成超連接地址，使用小節標題、腳註或引用參考名稱做爲超連接名稱就能夠生成隱式連接。

第一節 介紹
===========

其餘內容...

隱式連接到 `第一節 介紹`_，便可生成超連接。

第一節 介紹

其餘內容...

隱式連接到 第一節 介紹，便可生成超連接。

替換引用(Substitution Reference)

替換引用就是用定義的指令替換對應的文字或圖片，和內置指令(inline directives)相似。

這是 |logo| github的Logo，個人github用戶名是:|name|。

.. |logo| image:: https://help.github.com/assets/images/site/favicon.ico
.. |name| replace:: SeayXu

這是 GitHub的Logo，個人github用戶名是:SeayXu。

腳註引用(Footnote Reference)

腳註引用，有這幾個方式：有手工序號(標記序號123之類)、自動序號(填入#號會自動填充序號)、自動符號(填入*會自動生成符號)。

手工序號能夠和#結合使用，會自動延續手工的序號。

# 表示的方法能夠在後面加上一個名稱，這個名稱就會生成一個連接。

腳註引用一 [1]_
腳註引用二 [#]_
腳註引用三 [#連接]_
腳註引用四 [*]_
腳註引用五 [*]_
腳註引用六 [*]_

.. [1] 腳註內容一
.. [2] 腳註內容二
.. [#] 腳註內容三
.. [#連接] 腳註內容四 連接_
.. [*] 腳註內容五
.. [*] 腳註內容六
.. [*] 腳註內容七

腳註引用一 [1]
腳註引用二 [3]
腳註引用三 [4]
腳註引用四 [*]
腳註引用五 [†]
腳註引用六 [‡]

[1] 腳註內容一
[2] 腳註內容二
[3] 腳註內容三
[4] 腳註內容四 連接
[*] 腳註內容五
[†] 腳註內容六
[‡] 腳註內容七

引用參考(Citation Reference)

引用參考與上面的腳註有點相似。

引用參考的內容一般放在頁面結尾處，好比 [One]_，Two_

.. [One] 參考引用一
.. [Two] 參考引用二

引用參考的內容一般放在頁面結尾處，好比 [One]，Two

[One] 參考引用一
[Two] 參考引用二

註釋(Comments)

註釋以 .. 開頭，後面接註釋內容便可，能夠是多行內容，多行時每行開頭要加一個空格。

..
 我是註釋內容
 大家看不到我

關於 指令(Directives)，在下一篇中專門作語法說明。

若是有不正確的地方，但願你能指出。