角色¶

Sphinx 使用直譯文字角色在文件中插入語意標記。它們寫成 :rolename:`content`。

注意

預設角色 (`content`) 預設沒有特殊意義。您可以自由地將其用於任何您喜歡的事物，例如變數名稱；使用 default_role 設定值將其設定為已知的角色 – any 角色用於尋找任何事物，或 py:obj 角色用於尋找 Python 物件對此非常有用。

請參閱網域以瞭解網域新增的角色。

交叉參照¶

請參閱交叉參照。

交叉參照角色包括

any
doc
download
envvar
keyword
numref
option (以及已棄用的 cmdoption)
ref
term
token

行內程式碼高亮¶

:code:¶

一個行內程式碼範例。直接使用時，此角色僅顯示文字，不進行語法高亮，如同文字。

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

顯示：預設情況下，行內程式碼例如 1 + 2 僅顯示而不進行高亮。

與 code-block 指令不同，此角色不遵守由 highlight 指令設定的預設語言。

若要啟用語法高亮，您必須先使用 Docutils role 指令定義與特定語言關聯的自訂角色

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

若要顯示多行程式碼範例，請改用 code-block 指令。

數學¶

:math:¶

行內數學的角色。像這樣使用

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

顯示：自畢達哥拉斯以來，我們知道 \(a^2 + b^2 = c^2\)。

:eq:¶: 與 math:numref 相同。

其他語意標記¶

以下角色除了以不同樣式格式化文字外，不做任何特殊處理

:abbr:¶

縮寫。如果角色內容包含括號內的說明，將會特別處理：它將在 HTML 中顯示為工具提示，並且在 LaTeX 中僅輸出一次。

例如：:abbr:`LIFO (last-in, first-out)` 顯示 LIFO。

在 0.6 版本中新增。

:command:¶

作業系統層級命令的名稱，例如 rm。

例如：rm

:dfn:¶

標記文字中術語的定義實例。（不產生索引條目。）

例如：二進制模式

:file:¶

檔案或目錄的名稱。在內容中，您可以使用大括號來指示「變數」部分，例如

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

顯示：… 安裝在 /usr/lib/python3.x/site-packages …

在建構的文件中，x 將以不同的方式顯示，以指示它將被 Python 次要版本取代。

:guilabel:¶: 呈現為互動式使用者介面一部分的標籤應使用 guilabel 標記。這包括來自基於文字的介面的標籤，例如使用 curses 或其他基於文字的函式庫建立的介面。介面中使用的任何標籤都應使用此角色標記，包括按鈕標籤、視窗標題、欄位名稱、選單和選單選項名稱，甚至選取列表中的值。

在 1.0 版本中變更：GUI 標籤的快速鍵可以使用 & 符號包含；這將被移除並在輸出中顯示底線（例如：:guilabel:`&Cancel` 顯示 Cancel）。若要包含文字 & 符號，請將其加倍。

:kbd:¶: 標記按鍵順序。按鍵順序的形式可能取決於平台或應用程式特定的慣例。當沒有相關慣例時，修飾鍵的名稱應拼寫出來，以提高新使用者和非母語人士的可訪問性。例如，xemacs 按鍵順序可以標記為 :kbd:`C-x C-f`，但在沒有參考特定應用程式或平台的情況下，相同的順序應標記為 :kbd:`Control-x Control-f`，分別顯示 C-x C-f 和 Control-x Control-f。

:mailheader:¶: RFC 822 樣式郵件標頭的名稱。此標記並不暗示標頭正在電子郵件訊息中使用，但可用於參考任何相同「樣式」的標頭。這也用於各種 MIME 規格定義的標頭。標頭名稱應以通常在實務中找到的方式輸入，在有多個常用用法的情況下，優先使用駝峰式大小寫慣例。例如：:mailheader:`Content-Type` 顯示 Content-Type。

:makevar:¶

make 變數的名稱。

例如：help

:manpage:¶: Unix 手冊頁的參考，包括章節，例如 :manpage:`ls(1)` 顯示 ls(1)。如果定義了 manpages_url，則建立連結到外部網站以呈現手冊頁的超連結。

在 7.3 版本中變更：允許使用 <> 指定目標，如超連結。例如，:manpage:`blah <ls(1)>` 顯示 blah。

:menuselection:¶

選單選項應使用 menuselection 角色標記。這用於標記選單選項的完整順序，包括選取子選單和選擇特定操作，或此類順序的任何子序列。各個選項的名稱應以 --> 分隔。

例如，若要標記選項「開始 > 程式集」，請使用此標記

:menuselection:`Start --> Programs`

顯示：開始 ‣ 程式集

當包含包含某些尾隨指示符的選項時，例如某些作業系統用於指示命令開啟對話方塊的省略號，指示符應從選項名稱中省略。

menuselection 也支援 & 符號快速鍵，就像 guilabel 一樣。

:mimetype:¶

MIME 類型的名稱，或 MIME 類型的組件（主要或次要部分，單獨採用）。

例如：text/plain

:newsgroup:¶

Usenet 新聞群組的名稱。

例如：comp.lang.python

:program:¶

可執行程式的名稱。對於某些平台，這可能與可執行檔的檔名不同。特別是，對於 Windows 程式，應省略 .exe（或其他）副檔名。

例如：curl

:regexp:¶

正規表示式。不應包含引號。

例如：([abc])+

:samp:¶

一段文字，例如程式碼。在內容中，您可以使用大括號來指示「變數」部分，如 file 中所示。例如，在 :samp:`print(1+{variable})` 中，variable 部分將會被強調：print(1+variable)

如果您不需要「變數部分」指示，請改用標準 code 角色。

在 1.8 版本中變更：允許使用雙反斜線跳脫大括號。例如，在 :samp:`print(f"answer=\\{1+{variable}*2\\}")` 中，variable 部分將會被強調，並且跳脫的大括號將會顯示：print(f"answer={1+variable*2}")

還有一個 index 角色用於產生索引條目。

以下角色產生外部連結

:cve:¶

參考通用漏洞和披露記錄。這會產生適當的索引條目。產生文字「CVE 編號」；並連結到指定 CVE 的線上副本。您可以使用 :cve:`編號#anchor` 連結到特定章節。

例如：CVE 2020-10735

在 8.1 版本中新增。

:cwe:¶

參考通用弱點枚舉。這會產生適當的索引條目。產生文字「CWE 編號」；在 HTML 輸出中，連結到指定 CWE 的線上副本。您可以使用 :cwe:`編號#anchor` 連結到特定章節。

例如：CWE 787

在 8.1 版本中新增。

:pep:¶

參考 Python 增強提案。這會產生適當的索引條目。產生文字「PEP 編號」；在 HTML 輸出中，此文字是連結到指定 PEP 線上副本的超連結。您可以使用 :pep:`編號#anchor` 連結到特定章節。

例如：PEP 8

:rfc:¶

參考網際網路請求評論。這會產生適當的索引條目。產生文字「RFC 編號」；在 HTML 輸出中，此文字是連結到指定 RFC 線上副本的超連結。您可以使用 :rfc:`編號#anchor` 連結到特定章節。

例如：RFC 2324

請注意，由於您可以使用標準 reStructuredText 標記來達到該目的，因此沒有用於包含超連結的特殊角色。

替換¶

文件系統提供一些預設定義的替換。它們在建構設定檔中設定。

|release|: 由文件參考的專案版本取代。這意味著是包含 alpha/beta/候選發布標籤的完整版本字串，例如 2.5.2b3。由 release 設定。

|version|: 由文件參考的專案版本取代。這意味著僅包含主要和次要版本部分，例如 2.5，即使對於版本 2.5.1 也是如此。由 version 設定。

|today|: 由今天的日期（文件被讀取的日期）或在建構設定檔中設定的日期取代。通常具有 April 14, 2007 格式。由 today_fmt 和 today 設定。

|translation progress|: 由文件的翻譯進度取代。此替換旨在供文件翻譯人員使用，作為文件翻譯進度的標記。