reStructuredText 入門¶
reStructuredText 是 Sphinx 使用的預設純文字標記語言。本節簡要介紹 reStructuredText (reST) 的概念和語法，旨在為作者提供足夠的資訊以高效地撰寫文件。由於 reStructuredText 的設計宗旨是成為一種簡單、不引人注目的標記語言，因此這不會花費太長時間。
參見
權威的 reStructuredText 使用者文件。本文中的 “ref” 連結連結到 reStructuredText 參考中個別結構的描述。
段落¶
段落 (ref) 是 reStructuredText 文件中最基本的區塊。段落只是由一個或多個空白行分隔的文字塊。與 Python 中一樣，縮排在 reStructuredText 中很重要，因此同一段落的所有行都必須與相同的縮排層級左對齊。
行內標記¶
標準 reStructuredText 行內標記非常簡單：使用
一個星號：
*text*表示強調（斜體），兩個星號：
**text**表示強烈強調（粗體），以及反引號：
``text``表示程式碼範例。
如果星號或反引號出現在執行文字中，並且可能與行內標記分隔符號混淆，則必須使用反斜線跳脫。
請注意此標記的一些限制
它可能不會巢狀化，
內容可能不會以空白字元開始或結束：
* text*是錯誤的，它必須與周圍的文字用非單字字元分隔。使用反斜線跳脫的空格來解決此問題：
thisis\ *one*\ word。
這些限制可能會在 docutils 的未來版本中解除。
也可以使用角色來取代或擴充一些行內標記。請參閱 角色 以取得更多資訊。
列表和類似引用的區塊¶
列表標記 (ref) 很自然：只需在段落開頭放置一個星號並正確縮排即可。編號列表也是如此；它們也可以使用 # 符號自動編號
* 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.
巢狀列表是可能的，但請注意，它們必須與父列表項目用空白行分隔
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
定義列表 (ref) 的建立方式如下
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.
請注意，術語不能超過一行文字。
引用的段落 (ref) 是透過將它們縮排多於周圍的段落來建立的。
行區塊 (ref) 是一種保留換行符號的方式
| These lines are
| broken exactly like in
| the source file.
還有幾個更特殊的區塊可用
文字區塊¶
文字程式碼區塊 (ref) 是透過以特殊標記 :: 結束段落來引入的。文字區塊必須縮排（並且，像所有段落一樣，與周圍的段落用空白行分隔）
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.
:: 標記的處理方式很聰明
如果它作為自己的段落出現，則該段落將完全從文件中省略。
如果它前面有空白字元，則會移除標記。
如果它前面是非空白字元，則標記將替換為單個冒號。
這樣，上面範例的第一個段落中的第二個句子將呈現為「下一個段落是程式碼範例：」。
可以使用 highlight 指令在文件範圍內啟用這些文字區塊的程式碼醒目提示，並使用 highlight_language 設定選項在專案範圍內啟用。 code-block 指令可用於在逐區塊的基礎上設定醒目提示。這些指令將在稍後討論。
Doctest 區塊¶
Doctest 區塊 (ref) 是剪下並貼到 docstring 中的互動式 Python 會話。它們不需要 文字區塊 語法。doctest 區塊必須以空白行結束，並且不應以未使用的提示字元結束
>>> 1 + 1
2
表格¶
對於網格表格 (ref)，您必須自己「繪製」儲存格網格。它們看起來像這樣
+------------------------+------------+----------+----------+
| 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 | ... | ... | |
+------------------------+------------+----------+----------+
簡易表格 (ref) 更容易撰寫，但受到限制：它們必須包含多個列，並且第一列儲存格不能包含多行。它們看起來像這樣
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
支援另外兩種語法：CSV 表格和列表表格。它們使用顯式標記區塊。請參閱 表格 以取得更多資訊。
超連結¶
外部連結¶
使用 `連結文字 <https://domain.invalid/>`_ 作為行內網頁連結。如果連結文字應該是網址，則完全不需要特殊標記，剖析器會在一般文字中找到連結和郵件地址。
重要
URL 的連結文字和開頭 < 之間必須有一個空格。
您也可以分隔連結和目標定義 (ref)，如下所示
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
內部連結¶
內部連結是透過 Sphinx 提供的特殊 reStructuredText 角色完成的，請參閱關於特定標記、交叉參照任意位置 的章節。
章節¶
章節標題 (ref) 是透過使用標點符號底線標示（以及可選的上劃線標示）章節標題來建立的，長度至少與文字一樣
=================
This is a heading
=================
通常，沒有標題層級分配給某些字元，因為結構是從標題的順序確定的。但是，Python 開發人員指南中用於撰寫文件的慣例使用了此慣例，您可以遵循
#帶上劃線，表示部分*帶上劃線，表示章節=表示節-表示小節^表示子小節"表示段落
當然，您可以自由使用自己的標記字元（請參閱 reStructuredText 文件），並使用更深的巢狀層級，但請記住，大多數目標格式（HTML、LaTeX）對支援的巢狀深度有限制。
欄位列表¶
欄位列表 (ref) 是像這樣標記的欄位序列
:fieldname: Field content
它們通常用於 Python 文件中
def my_function(my_arg, my_other_arg):
"""A function just for me.
:param my_arg: The first of my arguments.
:param my_other_arg: The second of my arguments.
:returns: A message (just for me, of course).
"""
Sphinx 擴充了標準 docutils 行為，並攔截在文件開頭指定的欄位列表。請參閱 欄位列表 以取得更多資訊。
角色¶
角色或「自訂解譯文字角色」 (ref) 是一小段行內顯式標記。它表示封閉的文字應以特定方式解譯。Sphinx 使用此功能來提供語意標記和識別碼的交叉參照，如相應章節中所述。一般語法為 :rolename:`content`。
Docutils 支援以下角色
emphasis – 相當於
*emphasis*strong – 相當於
**strong**literal – 相當於
``literal``subscript – 下標文字
superscript – 上標文字
title-reference – 用於書籍、期刊和其他資料的標題
請參閱 角色 以取得 Sphinx 新增的角色。
顯式標記¶
「顯式標記」 (ref) 用於 reStructuredText 中大多數需要特殊處理的結構，例如腳註、特別醒目提示的段落、註解和通用指令。
顯式標記區塊以 .. 開頭的行開始，後跟空白字元，並以相同縮排層級的下一個段落終止。（顯式標記和一般段落之間需要有一個空白行。這聽起來可能有點複雜，但當您撰寫時，它就足夠直覺了。）
指令¶
指令 (ref) 是一種通用的顯式標記區塊。與角色一起，它是 reStructuredText 的擴充機制之一，而 Sphinx 大量使用它。
Docutils 支援以下指令
警告提示： attention、caution、danger、error、hint、important、note、tip、warning 和通用的 admonition。（大多數主題僅特別樣式化「note」和「warning」。）
圖片
其他內文元素
contents（本機的，即僅適用於目前檔案的目錄）
container（具有自訂類別的容器，有助於在 HTML 中產生外部
<div>）rubric（與文件章節無關的標題）
parsed-literal（支援行內標記的文字區塊）
epigraph（帶有可選屬性行的區塊引文）
highlights、pull-quote（具有其自身類別屬性的區塊引文）
compound（複合段落）
特殊表格
table（帶有標題的表格）
csv-table（從逗號分隔值產生的表格）
list-table（從列表清單產生的表格）
特殊指令
HTML 細節
meta（產生 HTML
<meta>標籤，另請參閱下方的 HTML Metadata）title（覆寫文件標題）
影響標記
default-role（設定新的預設角色）
role（建立新角色）
由於這些僅適用於每個檔案，因此最好使用 Sphinx 的工具來設定
default_role。
Sphinx 新增的指令在 指令 中說明。
基本上，指令由名稱、引數、選項和內容組成。（請記住此術語，它將在描述自訂指令的下一章中使用。）查看此範例，
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function 是指令名稱。此處給出了兩個引數，即第一行的其餘部分和第二行，以及一個選項 module（如您所見，選項在緊隨引數的行中給出，並以冒號表示）。選項必須縮排到與指令內容相同的層級。
指令內容在空白行之後，並相對於指令開頭縮排，或者如果存在選項，則縮排相同的量。
請小心，因為縮排不是固定的空白字元數，例如三個，而是任意數量的空白字元。當在整個文件中使用固定縮排時，這可能會令人驚訝，並且對於對空白字元敏感的指令可能會有所不同。比較
.. code-block::
:caption: A cool example
The output of this line starts with four spaces.
.. code-block::
The output of this line has no spaces at the beginning.
在第一個程式碼區塊中，內容的縮排由選項行固定為三個空格，因此內容以四個空格開頭。在後者中，縮排由內容本身固定為七個空格，因此它不會以空格開頭。
圖片¶
reStructuredText 支援圖片指令 (ref)，使用方式如下
.. image:: gnu.png
(options)
在 Sphinx 中使用時，給定的檔案名稱（此處為 gnu.png）必須相對於來源檔案，或絕對路徑，這表示它們相對於最上層來源目錄。例如，檔案 sketch/spam.rst 可以將圖片 images/spam.png 參照為 ../images/spam.png 或 /images/spam.png。
Sphinx 將在建置時自動將圖片檔案複製到輸出目錄的子目錄（例如，HTML 輸出的 _static 目錄。）
圖片大小選項（width 和 height）的解譯如下：如果大小沒有單位或單位是像素，則給定的大小僅在支援像素的輸出通道中受到尊重。其他單位（例如點的 pt）將用於 HTML 和 LaTeX 輸出（後者將 pt 替換為 bp，因為這是 TeX 單位，因此 72bp=1in）。
Sphinx 透過允許星號作為副檔名來擴充標準 docutils 行為
.. image:: gnu.*
然後 Sphinx 搜尋所有符合提供的模式的圖片，並確定它們的類型。然後，每個建置器都會從這些候選圖片中選擇最佳圖片。例如，如果給定檔案名稱 gnu.*，並且來源樹中存在兩個檔案 gnu.pdf 和 gnu.png，則 LaTeX 建置器將選擇前者，而 HTML 建置器將優先選擇後者。支援的圖片類型和選擇優先順序在 建置器 中定義。
請注意，圖片檔案名稱不應包含空格。
變更版本 0.4：新增了對以星號結尾的檔案名稱的支援。
變更版本 0.6：圖片路徑現在可以是絕對路徑。
變更版本 1.5：latex 目標支援像素（預設為 96px=1in）。
腳註¶
對於腳註 (ref)，使用 [#name]_ 標記腳註位置，並在文件底部「腳註」標題之後新增腳註內文，如下所示
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
您也可以明確編號腳註 ([1]_) 或使用沒有名稱的自動編號腳註 ([#]_)。
引文¶
支援標準 reStructuredText 引文 (ref)，並具有「全域」的附加功能，即可以從所有檔案參照所有引文。像這樣使用它們
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引文用法與腳註用法類似，但標籤不是數字或以 # 開頭。
替換¶
reStructuredText 支援「替換」 (ref)，它們是文字和/或標記，在文字中以 |name| 參照。它們像腳註一樣使用顯式標記區塊定義，如下所示
.. |name| replace:: replacement *text*
或這樣
.. |caution| image:: warning.png
:alt: Warning!
有關詳細資訊，請參閱 reStructuredText 替換參考。
如果您想為所有文件使用一些替換，請將它們放入 rst_prolog 或 rst_epilog 中，或將它們放入單獨的檔案中，並使用 include 指令將其包含在所有要使用它們的文件中。（請務必為包含檔案提供與其他來源檔案不同的副檔名，以避免 Sphinx 將其視為獨立文件。）
Sphinx 定義了一些預設替換，請參閱 替換。
HTML Metadata¶
meta 指令允許指定 Sphinx 文件頁面的 HTML metadata 元素。例如，指令
.. meta::
:description: The Sphinx documentation builder
:keywords: Sphinx, documentation, builder
將產生以下 HTML 輸出
<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">
此外，Sphinx 會將 meta 指令中指定的關鍵字新增至搜尋索引。因此，會考慮 meta 元素的 lang 屬性。例如，指令
.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
會將以下單字新增至具有不同語言設定的建置的搜尋索引
pleasefindthiskey、pleasefindthiskeytoo到英文建置；bittediesenkeyfinden到德文建置；backup到所有語言的建置。
原始碼編碼¶
由於在 reStructuredText 中包含特殊字元（如長破折號或版權符號）的最簡單方法是直接將它們寫為 Unicode 字元，因此必須指定編碼。Sphinx 預設假設來源檔案以 UTF-8 編碼；您可以使用 source_encoding 設定值來變更此設定。
陷阱¶
在撰寫 reStructuredText 文件時，人們經常遇到一些問題
行內標記的分隔： 如上所述，行內標記跨度必須與周圍的文字用非單字字元分隔，您必須使用反斜線跳脫的空格來解決此問題。有關詳細資訊，請參閱 參考文件。
沒有巢狀行內標記： 類似
*see :func:`foo`*的內容是不可能的。
註解¶
每個不是有效標記結構的顯式標記區塊（如上面的腳註）都被視為註解 (ref)。例如
.. This is a comment.您可以在註解開始後縮排文字以形成多行註解