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/

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

這篇文章來自我的Github,請參考 reference_。

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

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

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

這篇文章來自我的Github,請參考 SeayXu

更多信息參考 引用文檔_

這里是其他內容

.. _引用文檔:

這是引用部分的內容

更多信息參考 引用文檔

這里是其他內容

這是引用部分的內容

詞組(短語)引用/參考(phrase reference),引用的文字可以帶有空格或者符號,需要使用反引號引起來。

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

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

這篇文章來自我的Github,請參考 Quick reStructuredText

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

SeayXu_ 是 `我的 GitHub 用戶名`__。

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

__ SeayXu_

SeayXu我的 GitHub 用戶名

小節標題、腳注和引用參考會自動生成超鏈接地址,使用小節標題、腳注或引用參考名稱作為超鏈接名稱就可以生成隱式鏈接。

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

其他內容...

隱式鏈接到 `第一節 介紹`_,即可生成超鏈接。
第一節 介紹

其他內容…

隱式鏈接到 第一節 介紹,即可生成超鏈接。

替換引用(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),在下一篇中專門做語法說明。

如果有不正確的地方,希望你能指出。


注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2021 ITdaan.com