原文：http://blog.useasp.net/archive/2014/09/05/rst-file-restructuredtext-markup-syntax-quikstart.aspx?utm_source=tuicool

?

簡介

reStructuredText是一種輕量級的文本標記語言，直譯為：重構建的文本，是Python中Docutils項目的一部分。其一般保存的文件以.rst為后綴。在必要的時候，.rst文件可以被轉化成PDF或者HTML格式，也可以有Sphinx轉化為LaTex,man等格式，現在被廣泛的用于程序的文檔撰寫。

reStructuredText大致分章節，段落，塊和列表這幾種內容。而在這其中reStructuredText最主要用得到的標記也就是：

• 標題
• 段落
• 列表
• 表格
• 塊（如：代碼塊）
• 樣式

下面一一介紹：

標題（Title）

來看看標題的實例：

=================== 這就是一個標題 ===================---------------- 這也是一個章節標題 ----------------

怎么樣，看起來不難吧，你只要按這個寫法，就能被reStructuredText認識，并被解釋為章節標題。reStructuredText可用于作為標題修飾的字符有很多很多：

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

只要你想，上面的任意一個都可以用來作為標題的修飾符，當然，reStructuredText也是有推薦的，它推薦下面這些字符：

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

這些字符是上面一堆字符中稍微看起來不會那么奇怪的一部分，當然，個人建議不要那么花哨，盡量用這兩個中的一個：

= -

上面實例的寫法也許有點復雜，.rst文件中，你還可以只給出下半部分的字符即可：

這個標題和上面的一樣 ===================

TIPS：作為修飾的字符長度要大于等于文字長度。另外，標題是能夠嵌套的。

段落（?Paragraphs）

段落一般隸屬于某個章節中，是一塊左對齊并且沒有其他元素體標記的塊。在.rst文件中，段落和其他內容的分割是靠空行來完成，如果段落相較于其他的段落有縮進，reStructuredText會解析為引用段落，樣式上有些不同。

這里是一段reStructuredText的內容，它可以很長很長。。。。最后，末尾留出空行表示是本段落的結束即可。這里是另外一段reStructuredText的內容，這段內容和上一段之間，乃至后面的其他內容之間都要留出空行進行分割。這個也是段落，當時由于縮進了，會變成引用段落。顯示和直接的段落有點不同

列表(List)

列表在HTML中被分為兩種，一個是有序列表（Enumerated Lists），一種是無序列表（Bullet Lists），在reStructuredText中，我們也能找到這兩種列表，還有一種稱為定義列表（Definition Lists），這和HTML中的DL一樣，在.rst文件中可以支持嵌套列表。

無序列表?要求文本塊是以下面這些字符開始，并且后面緊跟空格，而后跟列表項的內容，其中列表項比趨勢左對齊并且有與列表對應的縮進。

* + - ? ? ?

還是那句話，用最常用的幾個字符就好，不用那么花哨。下面是示例：

- 這里是列表的第一個列表項- 這是第二個列表項- 這是第三個列表項- 這是縮進的第一個列表項注意，這里的縮進要和當前列表項的縮進同步。- 第一級的第四個列表項- 列表項之間要用個空格來分割。

有序列表?在格式上和無序列表差不多，但是在使用的前綴修飾符上，使用的不是無序列表那種字符，而是可排序的字符，可以識別的有下面這些：

arabic numerals: 1, 2, 3, ... (no upper limit). uppercase alphabet characters: A, B, C, ..., Z. lower-case alphabet characters: a, b, c, ..., z. uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).

如果你不想使用這些，在你標明第一個條目的序號字符后，第二個開始你還可以使用"#"號來讓reStructuredText自動生成需要的序號（Docutils >= 0.3.8）。

1. 第一項 巴拉巴拉好多內容在這里。。。#. 第二項a. 第二項的第一小項#. 第二項的第二小項#. 第三項

定義列表?：每個定義列表項里面包含術語（term），分類器（classifiers，可選）， 定義（definition）。術語是一行文字或者短語，分類器跟在術語后面，用“ ： ”(空格，冒號，空格）分隔。定義是相對于術語縮進后的一個塊。定義中可以包含多個段落或者其他的內容元素。術語和定義之間可以沒有空行，但是在定義列表前后必須要有空行的存在。下面是示例：

術語1 術語1的定義術語 2 術語2的定義,這是第一段術語2的定義，第二段術語 3 : 分類器 術語3的定義術語 4 : 分類器1 : 分類器2 術語4的定義

TIPS：在reStructuredText中，還有兩種列表，一種是字段列表（Field Lists），一種是選項列表（Option Lists）。由于是rst的語法入門教程，這里不做深入介紹

表格(Table)

reStructuredText提供兩種表格：網格表格（Grid?Tables）， 簡單表格（Simple 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. | +------------------------+------------+---------------------+來自docutils的幫助文檔.

TIPS：表頭行是可選的，如果你不需要，就可以不用"="來分割了。

簡單表格?：這種表格比網格表來說簡單許多，一般用于簡單的數據展示。其用于修飾的字符也僅兩個而已：

= -

一般用"="就能完成簡單表格的繪制，如果有表頭，同樣需要用"="將它和表體(body)內容分開，否則會被視為無表頭數據。

基本形式 ========`下面這種是最簡單的表格形式，當然你也可以去掉表頭展示。`===== ===== =======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 bulletlist (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表格，列表表格。這些復雜的格式就留給有興趣的朋友深入吧。

塊（Blocks）

塊在reStructuredText中的表現方式也有好幾種，但是最常見的是文字塊(Literal Blocks)。這種塊的表達非常簡單，就是在前面內容結束之后，用兩個冒號" :: "(空格[Optional]，冒號，冒號）來分割，并在之后緊接著插入空行，而后放入塊的內容，塊內容要相對之前的內容有縮進。

這里是塊之前的的內容。。。::這里是塊的內容。前面有縮進，空行，和::分隔符。此處內容會被一直視為塊內容空行也不能阻斷塊內容。。但是，當內容像這樣，不再和塊內容一樣縮進時，塊內容就自動的結束了。

這是塊的最簡單方式，一般我們編寫的代碼塊就是用這種方式表現（如下）， 除此之外，.rst還有引用文字塊(Quoted Literal Blocks)，行塊（Line Blocks），塊引用（Block Quotes）等。

下面是我們的測試代碼：::for i in [1,2,3,4,5]:print i# 代碼塊測試很簡單的代碼塊測試。

更多的塊內容，請參閱官方幫助文檔。

樣式(Style)

reStructuredText中支持對文本進行樣式控制，比如：粗體(Strong)，斜體(Italic)，等寬字體(Monospace)，引用(??interpreted text?)。

.. Strong EmphasisThis is **Strong Text**. HTML tag is strong.粗體.. Italic, EmphasisThis is *Emphasis* Text.這個HTML使用em， 斜體.. Interpreted TextThis is `Interpreted Text`. 注意，這個HTML一般用<cite>表示.. Inline LiteralsThis is ``Inline Literals``. HTML tag is <tt>. 等寬字體.

來點補充，如果你需要在文檔中插入超鏈接，那么你可以像下面這樣：

我這里是一個 鏈接_... _鏈接: http://blog.useasp.net

這種方式要求定義鏈接，而后引用鏈接。而且鏈接要有空格分隔前面的文字。這種方式略嫌麻煩，你可以用更加簡化的方式——個人比較推薦：

這里同樣是一個 `鏈接<http://blog.useasp.net>`_，不需要特別設置。

TIPS： 我們會發現，兩個處理連接的時候，都需要在鏈接文字前面要空格與前面進行分割，這個在英文當中比較好處理，因為單個詞之間有空格，而在中文中，字之間沒有空格，如果加入空格，在顯示時會有空格，影響觀感，為此，如果在中文中使用，需要考慮好。

到此為止，reStructuredText這個標記語言的基本用法已經展現完畢，進入實戰吧，騷年！

?

\ **修改SID方法：** 進入系統目錄C:\Windows\System32\Sysprep ，運行sysprep.exe程序，勾選上通用。

.. image:: ../static/picture.jpeg:height: 100px:width: 200 px:scale: 50 %:alt: alternate text:align: right

參考

在線reStructuredText編輯器，?編輯器1?，?編輯器2

? ? ?Sphinx 使用手冊:?http://zh-sphinx-doc.readthedocs.org/en/latest/contents.html

?? ? ? ? ? ? ? ? ? ? ? ? ? ? ?http://zh-sphinx-doc.readthedocs.org/en/latest/contents.html

?

轉載于:https://www.cnblogs.com/BuildingHome/p/4345156.html

總結

以上是生活随笔為你收集整理的reStructuredText(.rst)语法规则快速入门的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。