IT工程師數位筆記本

　　丑死人了，寫了些東西，看今天是周末，就閑得打包上傳到PyPI上，打包時反復測試，提示到沒有README.rst, 就將原來的Readme.md 該為這個名了，結果上傳上去，打開一看，天啊。一直很常見rst文件，得沒怎么研究過，趕緊腦補。

　　該文章轉載于：

　　http://blog.useasp.net/archive/2014/09/05/rst-file-restructuredtext-markup-syntax-quikstart.aspx

這幾天寫了個Python的 模塊，用Markdown寫個個README，傳到GitHub，感覺效果還不錯，就難抑沖動，打了個包，也想放到PyPI上，結果放上去，發現 README變成了源代碼。一查，才發現PyPI竟然不支持Markdown格式的README文件，好像支持的README要 reStructuredText格式的，對菜鳥的我來說這是個坑啊，好不容易在Emacs下用Markdown用的有點熟路了，結果發現卻不被支持。只 好重新看看reStructuredText的語法了，因此，也就有了此篇reStructuredText語法快速入門。

先文縐縐的來一段reStructuredText的介紹吧：

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

 好了，時間無多，直接正題：

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

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

標題（Title）

來看看標題的實例：

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

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

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

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

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

= -

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

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

段落（Paragraphs）

段落一般隸屬于某個章節中，是一塊左對齊并且沒有其他元素體標記的塊。在.rst文件中，段落和其他內容的分割是靠空行來完成，如果段落相較于其他的段落有縮進，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）。

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

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

 表格(Table)

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

 網格表中，共使用的符號有：

- = | +

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

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

= -

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

 TIPS：列需要和"="左對齊，不然可能會導致出錯；如果碰到第一列為空時，需要使用"\"來轉義，不然會被視為是上一行的延續；網格表和簡單 表中，簡單表比較適合展現簡單的數據，這些數據本身不需要太復雜的展現形式，而一旦碰到需要和并單元格這類的復雜操作，可能網格表會更加適合。

表格中還有更復雜的表格形式，比如：CSV表格，列表表格。這些復雜的格式就留給有興趣的朋友深入吧。

塊（Blocks）

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

這里是塊之前的的內容。。。::

   這里是塊的內容。前面有縮進，空行，和::分隔符。
    此處內容會被一直視為塊內容

    空行也不能阻斷塊內容。。

但是，當內容像這樣，不再和塊內容一樣縮進時，塊內容就自動的結束了。

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

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

樣式(Style)

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

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

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

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

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

參考文獻：

1. reStructuredText Markup Specification (本文有些例子是來源于此頁面)

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