reStructuredText 入門
本節簡要介紹了 新結構化文本 ~ reStructuredText的 (reST)的概念和語法, 旨在提供足夠的信息來幫助作者高效起草文件. 由於 reST 被設計成一個簡單的,不顯眼的標記語言, 所以,這不會花太長時間.
See also
權威 新結構化文本用戶文檔 在文章的 “ref” 鏈接中,有reST 各種結構的描述可供參考.
段落 Paragraphs
段落( 參考 )是 reST 文章中最常見的文本塊. 段落是由一個或多個空白分隔的文本塊. 同Python中的約定,在 reST 中使用縮進來標識, 因此, 所有同級段落,必須左對齊,使用同級縮進.
行內標記 Inline markup
標準的reST 行內標記很簡單:
- 單星號: *文本* 得 強調 (斜體 對中文一般效果不好) ,
- 雙星號: **文本** 得 加重 (加黑),
- 反引號: ``文本`` 得 代碼引用.
If asterisks or backquotes appear in running text and could be confused with inline markup delimiters, they have to be escaped with a backslash.
如果有星號或反引號出現在引用的文本, 就可能會弄亂內聯標記分隔符,這時,可以用反斜槓來轉義.
Be aware of some restrictions of this markup: 以下是知道這些標記的一些限制:
- 不可疊用
- 前後不能用空格: * text* 這樣會出錯,
- 必須和周圍文字用非單詞隔離, 一般使用轉義空白來完成: thisis\ *one*\ word
These restrictions may be lifted in future versions of the docutils. docutils未來版本中,可能取消這些限制.
reST also allows for custom “interpreted text roles”’, which signify that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is :rolename:`content`.
reST 也支持自定”文本詮釋規則”, 這意味着,任意由指定字符封閉的文本都可以用特定的方式來詮釋. Sphinx 就用這種形式來提供語義標記和交叉引用, 一般語法形如: :規則名:`內容`
Standard reST provides the following roles: 標準 reST 提供以下規則:
- emphasis – *emphasis* 的替代拼寫
- strong – **strong** 的替代拼寫
- literal – ``literal`` 的替代拼寫
- subscript – 下標
- superscript – 上標
- title-reference – 書籍/期刊/及其他材料的標題
參考: Inline markup Sphinx 追加的規則
列表和引用塊 Lists and Quote-like blocks
List markup (ref) is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for numbered lists; they can also be autonumbered using a # sign:: 列表標記(參考): 只要自然的在段落的開始放置一個星號並正確縮進. 這同樣適用於帶編號的列表; 也可以使用``#``簽署自動編號:
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:
嵌套的列表是允許的但必須用空行同父列表分離開:
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
定義列表(參考) 如下創建:
term (up to a line of text)
Definition of the term, which must be indented
and can even consist of multiple paragraphs
next term
Description.
Note that the term cannot have more than one line of text. 注意, 條目本身不能多行.
Quoted paragraphs (ref) are created by just indenting them more than the surrounding paragraphs. 創建引用段落 (參考)只需要用縮進和其它段落區分即可.
線塊 (ref) 是保留換行符的一種方法:
| These lines are
| broken exactly like in
| the source file.
還有其它特殊文本塊形式是支持的:
源代碼 Source Code
代碼文本塊 (參考) 由末尾是特殊標記 :: 的段落引發. 整個代碼文本塊必須縮進 (同所有的段落一樣,使用空白行和周圍文本完成分隔):
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
:: 標記是智能處置的:
- 如果作爲一個獨立段落出現,則和其它文本完全隔離
- 如果它緊跟有空格,則將被刪除不起作用
- 如果它在非空白字符之前,則替換爲普通的單一冒號
綜上,前述示例中的第二段代碼引用文本之前的一句會渲染爲 “The next paragraph is a code sample:”
That way, the second sentence in the above example’s first paragraph would be rendered as “The next paragraph is a code sample:”.
表格 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 | ... | ... | |
+------------------------+------------+----------+----------+
簡單表 (參考) 容易點,
但是有限制:至少要有一列,而且,第一行不能包含多行文本, 看起來象這樣:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
超鏈接 Hyperlinks
外部鏈接 External links
Use `Link text <http://example.com/>`_ for inline web links. If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text.
用 `Link text <http://example.com/>`_ 來記錄行內鏈接. 如果文字本身就是鏈接, 那不用作任何標記,解析器可以自動將鏈接和郵箱地址轉換爲超鏈接.
也可以單獨定義鏈接目標用引用(參考),比如:
This is a paragraph that contains `a link`_.
.. _a link: http://example.com/
內部鏈接 Internal links
Internal linking is done via a special reST role provided by Sphinx, see the section on specific markup, Cross-referencing arbitrary locations.
Sphinx 使用特殊 reST 規則支持內部鏈接, 詳細參考 定義規則
章節 Sections
Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:
章節頭部 (參考) 由下線(也可有上線)和包含標點的標題 組合創建, 其中下線要至少等於標準文本的長度:
=================
This is a heading
=================
Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, this convention is used which you may follow: 通常並沒有對標題的層級指定明確的標線字符. 不過,對於 Pyhton 文檔,可以使用如下約定:
- # 有上標線, 用以部分
- * 有上標線, 用以章節
- =, 用以小節
- -, 用以子節
- ^, 用以子節的子節
- ", 用以段落
Of course, you are free to use your own marker characters (see the reST documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.
當然,你可以自由的使用你自定的標識字符(參考 reST 文檔), 並使用更加深的嵌套層次, 不過,考慮到兼容多種輸出格式(HTML, LaTeX) 最好限制嵌套的深度.
直解標記 Explicit Markup
“Explicit markup” (ref) is used in reST for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.
“直解標記” (Explicit markup, 參考) 用以 reST 中需要特殊處理的各種內容, 如腳註,特殊高亮段落,註釋,以及通用指令.
An explicit markup block begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation. (There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.)
直解標記塊由``..``開始,緊後跟空格以及跟隨的同縮進的文本塊. (和正文間要有空白行來明確的加以區分. 可能聽起來有點複雜,但當你書寫時就能直觀的體驗到)
指令 Directives
A directive (ref) is a generic block of explicit markup. 指令(ref)就是一個標準的明確標記(Explicit Markup)塊. Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes heavy use of it. 除了規則,它是reST 的又一個擴展機制, Sphinx 大量使用了指令.
Docutils 支持以下指令:
-
警示 Admonitions: attention, caution, danger, error, hint, important, note, tip, warning and the generic admonition. (多數樣式目前僅支持 “note” 和 “warning” 好在都有針對的對象ID,很容易使用CSS進行定製 .)
-
圖像 Images:
-
其它行文元素 Additional body elements:
- contents (對諸如 本地文件 的內容表單)
- container (配有定製 class 的容器,以便生成HTML 中的 <div> )
- rubric (沒有到相對段落關係的標題 a heading without relation to the document sectioning)
- topic, sidebar (特殊高亮的正文元素 special highlighted body elements)
- parsed-literal (支持內嵌標記的文本塊)
- epigraph (有可選歸屬行的引用文本塊)
- highlights, pull-quote (有他們自己class屬性的文本塊)
- compound (複合段落)
-
特殊表格 Special tables:
- table (有標題的表格)
- csv-table (從csv數據生成的表格)
- list-table (從列表數據生成的表格)
-
特殊指令 Special directives:
-
HTML 專用 specifics:
-
影響標記 Influencing markup:
- default-role (設置新默認規則)
- role (創建新規則)
由於這些指令都只能作用到單一文件,所以,更好的使用 Sphinx 的方式是設置 default_role.
不要 使用指令 sectnum, header 和 footer.
Sphinx 增加的指令描述收集在: Sphinx Markup Constructs .
Basically, a directive consists of a name, arguments, options and content. (Keep this terminology in mind, it is used in the next chapter describing custom directives.) Looking at this example, 基本上一個指令由名稱,參數,選項和內容組成. (請記住這裏提及的幾個術語, 它們將在之後章節描述自定義指令) 從這個例子來看,:
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function 是指令名, 在頭兩行裏給出了兩個參數, 緊接着給出了一個 module 選項 (正如你所見,由冒號標明的 module 之後立即跟上參數) 選項必須縮進和指令內容有相同的縮進.
該指令的內容則是由一個空行和同樣的縮進來接上.
圖片 Images
reST 支持圖片指令 (ref), 這樣使用:
.. image:: gnu.png
(options)
在Sphinx 中使用時, 給入的文件名 (此處是 gnu.png) 必須是相對源文件目錄的路徑, 如果給的是絕對路徑形式,也意味着對源文件頂層目錄進行相對查找. 比如說, 文件 sketch/spam.rst 可以用路徑 ../images/spam.png 或 /images/spam.png. 來引用圖片 images/spam.png
Sphinx will automatically copy image files over to a subdirectory of the output directory on building (e.g. the _static directory for HTML output.) Sphinx 會自動將圖片複製到構築輸出目錄中的相關子目錄 (e.g. HTML輸出時的_static 目錄.)
Interpretation of image size options (width and height) is as follows: if the size has no unit or the unit is pixels, the given size will only be respected for output channels that support pixels (i.e. not in LaTeX output). Other units (like pt for points) will be used for HTML and LaTeX output.
圖片尺寸的解釋選項 (width 和 height)有如下規約: 如果大小沒給任何單位或單位是像素, 輸出通道優先使用像素(換言之,非LaTeX輸出). 其他單位(如 pt 或是 點) 將被用於HTML和LaTeX輸出.
Sphinx extends the standard docutils behavior by allowing an asterisk for the extension Sphinx 擴展了標準 docutils 行爲,支持如下的星號指代:
.. image:: gnu.*
Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Sphinx 會搜索所有匹配所提供模式的圖片, 並確定它們的類型. 每個構築器再從中選擇最佳的圖片. 例如, 如果給定文件名是 gnu.* , 源代碼樹中有兩個文件 gnu.pdf 和 gnu.png , LaTeX 構築器會選擇前者, HTML 構築器更傾向於後者.
Changed in version 0.4: 增加了文件名的星號後綴支持.
Changed in version 0.6: 開始支持絕對路徑的圖片
腳註 Footnotes
and add the footnote body at the bottom of the document after a “Footnotes” rubric heading, like so:: 腳註 (參考), 使用 [#name]_ 來標記位置, 並在文章底部 “Footnotes” 專欄之後追加腳註內容,如下使用:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_). 可以使用確切編號的腳註 (如: [1]_) 或是自動編號(用 [#]_).
引證 Citations
標準 reST 支持引證 (參考) , with the additional feature that they are “global”, i.e. all citations can be referenced from all files. Use them like so:: 有額外的功能是 “global”, 換言之,引證能從所有文件來引用. 這樣使用:
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #. 引證 的使用基本和腳註相同, 不過使用的標籤不是數字或是以 # 開始.
替換 Substitutions
reST 支持 “替換” (參考), 以 |name| 形式來定義替換的文本或是標記對象. 如腳註,可以在直解標記文本塊中聲明,形如:
.. |name| replace:: replacement *text*
或是:
.. |caution| image:: warning.png
:alt: Warning!
詳參 reST 替換參考 .
If you want to use some substitutions for all documents, put them into rst_prolog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)
如果你對所有文件使用一組替換, 把它們置入 rst_prolog 或放入一個單獨的文件, 並在所有相關文件中使用 incluse 指令引入, (請將此定義文件,使用和內容文件不同的後綴,否則,Sphinx 將視其爲獨立文章來嘗試解析)
Sphinx defines some default substitutions, see Substitutions. Sphinx 本身有些默認替換,參考 Substitutions .
註釋 Comments
所有直解標記文本塊都不算有效的標記構成 Every explicit markup block which isn’t a valid markup construct (like the footnotes above) is regarded as a comment (ref). For example:
沒有有效標記(如腳註)的直解標記文本塊就是註釋(參考) 例如:
.. This is a comment.
可以用縮進文本來進行多行註釋:
..
This whole indented block
is a comment.
Still in the comment.
源文本編碼 Source encoding
Since the easiest way to include special characters like em dashes or copyright signs in reST is to directly write them as Unicode characters, one has to specify an encoding. Sphinx assumes source files to be encoded in UTF-8 by default; you can change this with the source_encoding config value.
由於最簡單的方式,是在 reST 中將包括特殊字符(如長劃線或版權標記)都直接寫成Unicode字符. Sphinx 默認假設源文件是 utf-8 編碼. 你可以用配置項 source_encoding 來指定別的編碼.