指令

如先前討論，指令是一般的顯式標記區塊。雖然 Docutils 提供了許多指令，但 Sphinx 提供了更多，並將指令用作主要的擴充機制之一。

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

另請參閱

請參考 reStructuredText 入門 以取得 Docutils 提供的指令概述。

目錄

由於 reStructuredText 沒有互連多個文件或將文件分割成多個輸出檔案的功能，因此 Sphinx 使用自訂指令來新增文件組成之單一檔案之間的關聯性，以及目錄。toctree 指令是中心元素。

注意

使用 include 指令可以完成在一個檔案中簡單「包含」另一個檔案。

注意

若要為目前文件（.rst 檔案）建立目錄，請使用標準 reStructuredText contents 指令。

.. toctree::

此指令會在目前位置插入「TOC 樹狀結構」，使用指令主體中給定文件的個別 TOC（包括「子 TOC 樹狀結構」）。相對文件名稱（非以斜線開頭）相對於指令所在的文件，絕對名稱相對於來源目錄。可以指定數字 maxdepth 選項來指示樹狀結構的深度；預設情況下，會包含所有層級。[1]

「TOC 樹狀結構」的表示方式在每個輸出格式中都會變更。輸出多個檔案的建置器（例如 HTML）會將其視為超連結的集合。另一方面，輸出單一檔案的建置器（例如 LaTeX、man page 等）會將其替換為 TOC 樹狀結構上文件的內容。

請考慮以下範例（取自 Python 文件庫參考索引）

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

這完成了兩件事

  • 會插入所有這些文件的目錄，最大深度為 2，這表示一個巢狀標題。也會考慮這些文件中的 toctree 指令。

  • Sphinx 知道文件 intro、strings 等的相對順序，並且知道它們是所示文件（程式庫索引）的子文件。從此資訊中，它會產生「下一章」、「上一章」和「父章」連結。

條目

toctree 中的文件標題會從參照文件的標題自動讀取。如果這不是您想要的，您可以使用類似 reStructuredText 超連結（和 Sphinx 的 交叉參照語法）的語法來指定明確的標題和目標。看起來像這樣

.. toctree::

   intro
   All about strings <strings>
   datatypes

上面的第二行將連結到 strings 文件，但會使用標題「All about strings」而不是 strings 文件的標題。

您也可以新增外部連結，方法是提供 HTTP URL 而不是文件名稱。

特殊條目名稱 self 代表包含 toctree 指令的文件。如果您想要從 toctree 產生「網站地圖」，這非常有用。

最後，來源目錄（或子目錄）中的所有文件都必須出現在某些 toctree 指令中；如果 Sphinx 找到未包含的檔案，它會發出警告，因為這表示此檔案無法透過標準導覽存取。

使用 exclude_patterns 明確地從建置中排除文件或目錄。使用 「孤立」中繼資料 讓文件建置，但通知 Sphinx 它無法透過 toctree 存取。

「根文件」（由 root_doc 選取）是 TOC 樹狀結構階層的「根」。如果未提供 :maxdepth: 選項，則可以用作文件的主要頁面，或用作「完整目錄」。

在版本 0.6 中變更：新增了對外部連結和「self」參照的支援。

選項

:class: class names （類別名稱的列表，以空格分隔）

指派 類別屬性。這是 通用選項。例如

.. toctree::
   :class: custom-toc

在版本 7.4 中新增。

:name: label （文字）

可以使用 ref 參照的隱含目標名稱。這是 通用選項。例如

.. toctree::
   :name: mastertoc

   foo

在版本 1.3 中新增。

:caption: （文字）

將標題新增至 toctree。例如

.. toctree::
   :caption: Table of Contents

    foo

在版本 1.3 中新增。

:numbered:
:numbered: depth

如果您希望即使在 HTML 輸出中也有章節編號，請將 :numbered: 選項新增至最上層 toctree。例如

.. toctree::
   :numbered:

   foo
   bar

章節編號隨後從 foo 的標題開始。子 toctree 會自動編號（不要將 numbered 旗標提供給這些）。

也可以透過將深度作為數字引數提供給 numbered，對特定深度進行編號。

在版本 0.6 中新增。

在版本 1.1 中變更：新增了數字depth引數。

:titlesonly:

僅列出文件標題，而非相同層級的其他標題。例如

.. toctree::
   :titlesonly:

   foo
   bar

在版本 1.0 中新增。

:glob:

剖析 toctree 條目中的 glob 萬用字元。所有條目都會與可用文件列表進行比對，比對結果會依字母順序插入列表。例如

.. toctree::
   :glob:

   intro*
   recipe/*
   *

這會先包含名稱以 intro 開頭的所有文件，然後是 recipe 資料夾中的所有文件，然後是所有剩餘文件（當然，不包括包含指令的文件）。[2]

在版本 0.3 中新增。

:reversed:

反轉列表中條目的順序。當使用 :glob: 選項時，這特別有用。

在版本 1.5 中新增。

:hidden:

隱藏的 toctree 僅定義文件階層。它不會在指令位置將連結插入文件中。

如果您有其他導覽方式，例如透過手動連結、HTML 側邊欄導覽，或者如果您在最上層 toctree 上使用 :includehidden: 選項，這就很有意義。

在版本 0.6 中新增。

:includehidden:

如果您想要顯示完整文件結構的全域目錄，您可以將 :includehidden: 選項新增至最上層 toctree 指令。然後可以使用 :hidden: 選項將子頁面上的所有其他 toctree 設為不可見。具有 :includehidden: 的最上層 toctree 隨後會包含其條目。

在版本 1.2 中新增。

特殊名稱

Sphinx 保留了一些文件名稱供自己使用；您不應嘗試建立具有這些名稱的文件 – 這會導致問題。

特殊文件名稱（以及為其產生的頁面）為

  • genindex

    這用於一般索引，其中填入了來自 index 指令和所有產生索引的 物件描述 的條目。例如，請參閱 Sphinx 的索引。

  • modindex

    這用於 Python 模組索引，其中包含每個 py:module 指令的一個條目。例如，請參閱 Sphinx 的 Python 模組索引。

  • search

    這用於搜尋頁面，其中包含一個表單，該表單使用產生的 JSON 搜尋索引和 JavaScript 來對產生的文件進行全文搜尋以尋找搜尋字詞；它適用於每個主要瀏覽器。例如，請參閱 Sphinx 的搜尋頁面。

  • 每個以 _ 開頭的名稱

    雖然 Sphinx 目前使用的此類名稱很少，但您不應建立具有此類名稱的文件或包含文件的目錄。（使用 _ 作為自訂範本目錄的前綴是可以的。）

警告

請小心檔案名稱中的不尋常字元。某些格式可能會以意外的方式解譯這些字元

  • 請勿對 HTML 基礎格式使用冒號 :。其他部分的連結可能無法運作。

  • 請勿對 ePub 格式使用加號 +。可能找不到某些資源。

段落層級標記

這些指令會建立簡短的段落，可用於資訊單元以及一般文字中。

提示、訊息和警告

提示指令會建立「提示」元素，這是一個標準化的系統，用於傳達不同類型的資訊，從有用的 tip 到至關重要的 danger 問題。這些指令可用於任何普通內文元素可以使用的位置，並且可以包含任意內文元素。有九個特定的具名提示和通用的 admonition 指令。

.. attention::

需要讀者注意的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

注意

請注意。

.. caution::

讀者應謹慎的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

注意

請務必謹慎。

.. danger::

如果不注意，可能會導致迫在眉睫的危險的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

危險

不要以為可以逃避危險，因為遲早愛會親自復仇。

.. error::

與某些描述的失敗模式相關的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

錯誤

錯誤 418：我是個茶壺。

.. hint::

對讀者有幫助的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

提示

在花盆下尋找。

.. important::

至關重要且讀者絕不能忽略的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

重要

這是一項至關重要的聲明。

.. note::

讀者應知道的特別重要的資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

注意

此功能不適合傳送垃圾郵件罐頭。

.. tip::

對讀者有用的一些資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

提示

記得擦防曬乳！

.. warning::

讀者應非常注意的重要資訊。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

警告

小心惡犬。

.. admonition:: title

通用提示，具有可選標題。指令的內容應以完整的句子撰寫，並包含所有適當的標點符號。

範例

這是一個標題

這是提示的內容。

.. seealso::

許多章節都包含模組文件或外部文件的參考列表。這些列表是使用 seealso 指令建立的。

seealso 指令通常放在任何子章節之前的章節中。seealso 指令的內容應該是單行或 reStructuredText 定義列表。

範例

.. seealso::

   Python's :py:mod:`zipfile` module
      Documentation of Python's standard :py:mod:`zipfile` module.

   `GNU tar manual, Basic Tar Format <https://example.org>`_
      Documentation for tar archive files, including GNU tar extensions.

另請參閱

模組 zipfile

zipfile 標準模組的文件。

GNU tar 手冊，基本 Tar 格式

tar 封存檔案的文件，包括 GNU tar 擴充功能。

可折疊文字

在版本 8.2 中新增。

每個提示指令都支援 :collapsible: 選項，使提示的內容可折疊（在輸出格式支援的情況下）。這對於並非總是相關的內容很有用。預設情況下，可折疊提示最初是開啟的，但可以使用 :collapsible: 選項的 open 和 closed 引數來控制此預設狀態，這些引數會變更預設狀態。在不支援可折疊內容的輸出格式中，文字始終會包含在內。例如

.. note::
   :collapsible:

   This note is collapsible, and initially open by default.

.. admonition:: Example
   :collapsible: open

   This example is collapsible, and initially open.

.. hint::
   :collapsible: closed

   This hint is collapsible, but initially closed.
注意

此注意事項是可折疊的，預設為初始開啟。

範例

此範例是可折疊的，且初始開啟。

提示

此提示是可折疊的，但初始關閉。

描述版本之間的變更

.. versionadded:: version [簡短說明]

此指令記錄新增所述功能的專案版本。當這適用於整個模組或元件時，應將其放在任何散文之前的相關章節頂端。

必須提供第一個引數，即相關版本；您可以新增第二個引數，其中包含變更的簡短說明。

注意

指令標頭和說明之間不得有空白行；這是為了使這些區塊在標記中視覺上連續。

範例

.. versionadded:: 2.5
   The *spam* parameter.

在版本 2.5 中新增：spam 參數。

.. versionchanged:: version [簡短說明]

類似於 versionadded，但描述指定的功能在某種程度上變更的時間和內容（新參數、變更的副作用等）。

範例

.. versionchanged:: 2.8
   The *spam* parameter is now of type *boson*.

在版本 2.8 中變更：spam 參數現在的類型為 boson。

.. deprecated:: version [簡短說明]

類似於 versionadded，但描述功能何時已棄用。也可以提供簡短說明，例如告訴讀者改用什麼。

範例

.. deprecated:: 3.1
   Use :py:func:`spam` instead.

自版本 3.1 起已棄用：改用 spam()。

.. versionremoved:: version [簡短說明]

類似於 versionadded，但描述功能何時已移除。可以提供說明，告訴讀者改用什麼，或功能移除的原因。

在版本 7.3 中新增。

範例

.. versionremoved:: 4.0
   The :py:func:`spam` function is more flexible, and should be used instead.

在版本 4.0 中移除：spam() 函式更具彈性，應改為使用。

呈現

.. rubric:: title

標題就像一個非正式標題，不對應於文件的結構，即它不會建立目錄節點。

注意

如果標題的標題是「Footnotes」（或選定語言的對等詞），則 LaTeX 寫入器會忽略此標題，因為它被假定僅包含註腳定義，因此會建立一個空白標題。

選項

:class: class names （類別名稱的列表，以空格分隔）

指派 類別屬性。這是 通用選項。

:name: label （文字）

可以使用 ref 參照的隱含目標名稱。這是 通用選項。

:heading-level: n （數字，從 1 到 6）

在版本 7.4.1 中新增。

使用此選項可指定標題的標題層級。在這種情況下，對於 HTML 輸出，標題將呈現為 <h1> 到 <h6>，對於 LaTeX，則呈現為對應的非編號分節命令（請參閱 latex_toplevel_sectioning）。

.. centered::

此指令會建立置中的粗體文字行。

自版本 1.1 起已棄用：此僅限呈現的指令是舊版本的遺留物。請改用 rst-class 指令並新增適當的樣式。

.. hlist::

此指令必須包含項目符號列表。它會將其轉換為更精簡的列表，方法是水平分佈多個項目，或減少項目之間的間距，具體取決於建置器。

選項

:columns: n （整數）

欄數；預設值為 2。例如

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

在版本 0.6 中新增。

顯示程式碼範例

在 Sphinx 中有多種方式可以顯示語法突顯的文字程式碼區塊

Doctest 程式碼區塊僅能用於展示互動式的 Python 會話，而其餘三種則可用於其他語言。在這三種之中，當整份文件，或至少是大部分章節，都使用具有相同語法且應以相同方式設定樣式的程式碼區塊時，純文字區塊就很有用。另一方面，當您想要更精細地控制每個區塊的樣式，或者當您的文件包含使用多種不同語法的程式碼區塊時，code-block 指令會更有意義。最後，literalinclude 指令對於在文件中包含整個程式碼檔案非常有用。

在所有情況下，語法突顯皆由 Pygments 提供。當使用純文字區塊時，這會使用原始檔中任何 highlight 指令進行設定。當遇到 highlight 指令時，會一直使用它，直到遇到下一個 highlight 指令為止。如果檔案中沒有 highlight 指令，則會使用全域突顯語言。預設值為 python，但可以使用 highlight_language 設定值進行設定。支援以下值

  • none (不突顯)

  • default (類似於 python3，但會回退到 none，且在突顯失敗時不會發出警告；當未設定 highlight_language 時的預設值)

  • guess (讓 Pygments 根據內容猜測詞法分析器，僅適用於某些容易辨識的語言)

  • python

  • rest

  • c

  • … 以及 Pygments 支援的任何其他 詞法分析器別名

如果使用選定的語言突顯失敗 (即 Pygments 發出 “Error” 符號)，則區塊將不會以任何方式突顯。

重要

支援的詞法分析器別名列表與 Pygment 版本相關。如果您想確保一致的突顯，您應該固定您的 Pygments 版本。

.. highlight:: language

範例

.. highlight:: c

此語言會一直使用到遇到下一個 highlight 指令為止。如先前所述，language 可以是 Pygments 支援的任何詞法分析器別名。

選項

:linenothreshold: threshold (number (optional))

啟用為程式碼區塊產生行號。

此選項採用一個可選的數字作為 threshold 參數。如果給定任何 threshold，則指令只會為行數超過 N 行的程式碼區塊產生行號。如果未給定，則會為所有程式碼區塊產生行號。

範例

.. highlight:: python
   :linenothreshold: 5
:force: (no value)

如果給定此選項，則會忽略突顯時的次要錯誤。

在 2.1 版本中新增。

.. code-block:: [language]
.. sourcecode:: [language]
.. code:: [language]

範例

.. code-block:: ruby

   Some Ruby code.

指令的別名 sourcecode 也適用。此指令接受語言名稱作為引數。它可以是 Pygments 支援的任何詞法分析器別名。如果未給定，則會使用 highlight 指令的設定。如果未設定，則會使用 highlight_language。若要內嵌在其他文字中顯示程式碼範例，而不是作為單獨的區塊，您可以使用 code 角色來代替。

在 2.0 版本中變更：language 引數變為可選。

選項

:linenos: (no value)

啟用為程式碼區塊產生行號

.. code-block:: ruby
   :linenos:

   Some more Ruby code.
:lineno-start: number (number)

設定程式碼區塊的第一個行號。如果存在，也會自動啟用 linenos 選項

.. code-block:: ruby
   :lineno-start: 10

   Some more Ruby code, with line numbering starting at 10.

在版本 1.3 中新增。

:emphasize-lines: line numbers (comma separated numbers)

強調程式碼區塊的特定行

.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print('This line is highlighted.')
       print('This one is not...')
       print('...but this one is.')

在 1.1 版本中新增。

在 1.6.6 版本中變更：LaTeX 支援 emphasize-lines 選項。

:force: (no value)

忽略突顯時的次要錯誤。

在 2.1 版本中新增。

:caption: caption of code block (text)

為程式碼區塊設定標題。

在版本 1.3 中新增。

:name: a label for hyperlink (text)

定義可以使用 ref 參照的隱式目標名稱。例如

.. code-block:: python
   :caption: this.py
   :name: this-py

   print('Explicit is better than implicit.')

為了使用 ref 或 numref 角色交叉參照程式碼區塊，必須同時定義 name 和 caption。然後，可以將 name 的引數提供給 numref 以產生交叉參照。範例

See :numref:`this-py` for an example.

當使用 ref 時，即使只定義了 name，只要給定明確的標題，就可以產生交叉參照。範例

See :ref:`this code snippet <this-py>` for an example.

在版本 1.3 中新增。

:class: class names (a list of class names separated by spaces)

指派 類別屬性。這是 通用選項。

在 1.4 版本中新增。

:dedent: number (number or no value)

從程式碼區塊中移除縮排字元。當給定數字時，會移除開頭的 N 個字元。當未給定引數時，會透過 textwrap.dedent() 移除開頭的空格。例如

.. code-block:: ruby
   :linenos:
   :dedent: 4

       some ruby code

在版本 1.3 中新增。

在 3.5 版本中變更：支援自動移除縮排。

.. literalinclude:: filename

冗長的逐字文字顯示可以透過將範例文字儲存在僅包含純文字的外部檔案中來包含。可以使用 literalinclude 指令包含該檔案。[3] 例如，若要包含 Python 原始碼檔案 example.py，請使用

.. literalinclude:: example.py

檔案名稱通常相對於目前檔案的路徑。但是，如果它是絕對路徑 (以 / 開頭)，則相對於最上層來源目錄。

通用選項

:class: class names (a list of class names, separated by spaces)

指派 類別屬性。這是 通用選項。

在 1.4 版本中新增。

:name: label (text)

可以使用 ref 參照的隱含目標名稱。這是 通用選項。

在版本 1.3 中新增。

:caption: caption (text)

在包含的內容上方新增標題。如果未給定引數，則檔案名稱會用作標題。

在版本 1.3 中新增。

格式化選項

:dedent: number (number or no value)

從包含的內容中移除縮排字元。當給定數字時，會移除開頭的 N 個字元。當未給定引數時，會移除所有常見的開頭縮排 (使用 textwrap.dedent())。

在版本 1.3 中新增。

在 3.5 版本中變更：支援自動移除縮排。

:tab-width: N (number)

將 Tab 字元展開為 N 個空格。

在版本 1.0 中新增。

:encoding: (text)

明確指定檔案的編碼。這會覆寫預設編碼 (source_encoding)。例如

.. literalinclude:: example.txt
   :encoding: latin-1

在 0.4.3 版本中新增。

:linenos: (no value)

在包含的內容旁邊顯示行號。預設情況下，行號從 1 開始計數。可以使用 :lineno-start: 和 :lineno-match: 選項變更此設定。

:lineno-start: number (number)

設定要顯示的第一行的行號。如果給定，則會自動啟用 :linenos:。

:lineno-match:

當僅包含檔案的一部分並顯示原始行號時。這僅在選取範圍由連續行組成時才允許。

在版本 1.3 中新增。

:emphasize-lines: line numbers (comma separated numbers)

強調包含內容的特定行。例如

.. literalinclude:: example.txt
   :emphasize-lines: 1,2,4-6
:language: language (text)

選取與目前檔案的標準語言不同的突顯語言 (Pygments 詞法分析器) (由 highlight 或 highlight_language 設定)。

:force: (no value)

忽略突顯時的次要錯誤。

在 2.1 版本中新增。

用於選取要包含的內容的選項

:pyobject: object (text)

對於 Python 檔案，僅包含指定的類別、函式或方法

.. literalinclude:: example.py
   :pyobject: Timer.start

在版本 0.6 中新增。

:lines: line numbers (comma separated numbers)

明確指定要包含的行

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

這包括第 1 行、第 3 行、第 5 至 10 行以及第 20 行到結尾。

在版本 0.6 中新增。

:start-at: text
:start-after: text
:end-before: text
:end-at: text

另一種控制要包含檔案的哪個部分的方法是使用 start-after 和 end-before 選項 (或僅其中之一)。如果將 start-after 作為字串選項給定，則僅包含在包含該字串的第一行之後的行。如果將 end-before 作為字串選項給定，則僅包含在包含該字串的第一行之前的行。start-at 和 end-at 選項的行為方式類似，但包含相符字串的行也會包含在內。

start-after/start-at 和 end-before/end-at 可以具有相同的字串。start-after/start-at 會篩選在包含選項字串的行之前的行 (start-at 會保留該行)。然後 end-before/end-at 會篩選在包含選項字串的行之後的行 (end-at 會保留該行，而 end-before 會跳過第一行)。

在 0.6 版本中新增：新增 start-after 和 end-before 選項。

在 1.5 版本中新增：新增 start-at 和 end-at 選項。

提示

若要僅選取 INI 檔案 (例如以下檔案) 的 [second-section]，請使用 :start-at: [second-section] 和 :end-before: [third-section]

[first-section]
var_in_first=true

[second-section]
var_in_second=true

[third-section]
var_in_third=true

當使用標籤註解時，這些選項可能很有用。使用 :start-after: [initialise] 和 :end-before: [initialised] 會保留以下兩個註解之間的行

if __name__ == "__main__":
    # [initialise]
    app.start(":8000")
    # [initialised]

當以任何上述方式選取行時，emphasize-lines 中的行號會參照這些選取的行，從 1 開始連續計數。

:prepend: line (text)

在包含的程式碼之前預先加入一行。例如，當突顯不包含 <?php 或 ?> 標記的 PHP 程式碼時，這可能很有用。

在版本 1.0 中新增。

:append: line (text)

在包含的程式碼之後附加一行。例如，當突顯不包含 <?php 或 ?> 標記的 PHP 程式碼時，這可能很有用。

在版本 1.0 中新增。

:diff: filename

顯示兩個檔案的差異。例如

.. literalinclude:: example.txt
   :diff: example.txt.orig

這會以 unified diff 格式顯示 example.txt 和 example.txt.orig 之間的差異。

在版本 1.3 中新增。

在 0.6 版本中變更：新增支援絕對檔案名稱。

在 1.6 版本中變更：當同時使用 start-after 和 lines 時，根據 start-after 的第一行會被視為 lines 的行號 1。

詞彙表

.. glossary::

此指令必須包含類似 reStructuredText 定義列表的標記，其中包含術語和定義。然後可以使用 term 角色參照這些定義。範例

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

與一般定義列表相反，每個條目允許多個術語，並且術語中允許內嵌標記。您可以連結到所有術語。例如

.. glossary::

   term 1
   term 2
      Definition of both terms.

(當詞彙表排序時，第一個術語決定排序順序。)

如果您想為一般索引條目指定「分組鍵」，您可以將「鍵」作為「術語 : 鍵」放置。例如

.. glossary::

   term 1 : A
   term 2 : B
      Definition of both terms.

請注意，「鍵」按原樣用作分組鍵。「鍵」不會正規化；鍵「A」和「a」會變成不同的群組。「鍵」中的所有字元都用於分組鍵，而不是第一個字元；它用於「組合字元序列」和「替代對」分組鍵。

在 i18n 情況下，即使原始文字只有「術語」部分，您也可以指定「本地化術語 : 鍵」。在這種情況下，翻譯後的「本地化術語」將分類在「鍵」群組中。

在 1.1 版本中變更：現在支援每個術語多個術語和內嵌標記。

在 1.4 版本中變更：詞彙表術語的索引鍵應視為實驗性功能。

選項

:sorted:

按字母順序排序條目。

在版本 0.6 中新增。

在 4.4 版本中變更：在國際化文件中，根據翻譯後的術語排序。

元資訊標記

.. sectionauthor:: name <email>

識別目前章節的作者。引數應包含作者的姓名，以便用於簡報和電子郵件地址。地址的網域名稱部分應為小寫。範例

.. sectionauthor:: Guido van Rossum <[email protected]>

預設情況下，此標記不會以任何方式反映在輸出中 (它有助於追蹤貢獻)，但您可以將組態值 show_authors 設定為 True，使其在輸出中產生段落。

.. codeauthor:: name <email>

codeauthor 指令 (可以出現多次) 會命名所述程式碼的作者，就像 sectionauthor 命名文件片段的作者一樣。只有當 show_authors 組態值為 True 時，它才會產生輸出。

索引產生標記

Sphinx 會自動從所有物件描述 (例如函式、類別或屬性) 建立索引條目，如 網域 中所述。

但是，也有可用的明確標記，使索引更全面，並在資訊主要不包含在資訊單元 (例如語言參考) 中的文件中啟用索引條目。

.. index:: <entries>

此指令包含一個或多個索引條目。每個條目都包含一個類型和一個值，以冒號分隔。

例如

.. index::
   single: execution; context
   pair: module; __main__
   pair: module; sys
   triple: module; search; path
   seealso: scope

The execution context
---------------------

...

此指令包含五個條目，這些條目將轉換為產生索引中的條目，這些條目連結到索引陳述式的確切位置 (或者，在離線媒體的情況下，連結到對應的頁碼)。

由於索引指令在其在來源中的位置產生交叉參照目標，因此將它們放在它們參照的內容之前是有意義的 – 例如標題，如上面的範例所示。

可能的條目類型為

single

建立單個索引條目。可以透過用分號分隔子條目文字來建立子條目 (以下標記也用於描述建立哪些條目)。範例

.. index:: single: execution
           single: execution; context

  • single: execution 建立一個標記為 execution 的索引條目。

  • single: execution; context 建立一個標記為 context 的 execution 子條目。

pair

建立兩個索引條目的快捷方式。值對必須以分號分隔。範例

.. index:: pair: loop; statement

這將建立兩個索引條目；loop; statement 和 statement; loop。

triple

建立三個索引條目的快捷方式。所有三個值都必須以分號分隔。範例

.. index:: triple: module; search; path

這會建立三個索引條目；module; search path、search; path, module 和 path; module search。

參見

建立參照至另一個條目的索引條目的快捷方式。範例

.. index:: see: entry; other

這會建立一個從 entry 參照到 other 的索引條目（即「entry」：參見「other」）。

另請參閱

如同 see，但插入「另請參閱」而不是「參見」。

模組、關鍵字、運算子、物件、例外、陳述式、內建

這些已棄用的快捷方式都會建立兩個索引條目。例如，module: hashlib 會建立條目 module; hashlib 和 hashlib; module。

版本 1.0 開始棄用：這些 Python 特有的條目類型已被棄用。

版本 7.1 變更：移除版本設定為 Sphinx 9.0。現在使用這些條目類型將會發出 index 類別的警告。

您可以透過在「主要」索引條目前面加上驚嘆號來標記它們。在產生的索引中，對「主要」條目的參照會被強調。例如，如果兩個頁面包含

.. index:: Python

而一個頁面包含

.. index:: ! Python

那麼，在三個反向連結中，指向後者的頁面的反向連結會被強調。

對於僅包含「single」條目的索引指令，有一種簡寫符號

.. index:: BNF, grammar, syntax, notation

這會建立四個索引條目。

版本 1.1 變更：新增了 see 和 seealso 類型，以及標記主要條目。

選項

:name: 超連結 的 標籤 (文字)

定義可以使用 ref 參照的隱式目標名稱。例如

.. index:: Python
   :name: py-index

版本 3.0 新增。

:index:

雖然 index 指令是區塊層級的標記，並連結到下一個段落的開頭，但也有一個對應的角色，可以直接在使用的位置設定連結目標。

角色的內容可以是簡單的詞組，然後保留在文字中並用作索引條目。它也可以是文字和索引條目的組合，樣式類似於交叉參照的明確目標。在這種情況下，「目標」部分可以是如上針對指令所述的完整條目。例如

This is a normal reStructuredText :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.

在 1.1 版本中新增。

根據標籤包含內容

.. only:: <expression>

僅當 expression 為真時，才包含指令的內容。表達式應由標籤組成，如下所示

.. only:: html and draft

未定義的標籤為假，已定義的標籤為真（標籤可以透過 --tag 命令列選項或在 conf.py 內定義，請參閱 此處）。布林表達式（如 (latex or html) and draft）受到支援，並且可以使用括號。

目前建置器 (html、latex 或 text) 的 format 和 name 始終設定為標籤 [4]。為了明確區分 format 和 name，它們也會以前綴 format_ 和 builder_ 新增，例如 epub 建置器定義了標籤 html、epub、format_html 和 builder_epub。

這些標準標籤是在讀取組態檔之後設定的，因此它們在那裡不可用。

所有標籤都必須遵循 識別符號和關鍵字 文件中規定的標準 Python 識別符號語法。也就是說，標籤表達式只能由符合 Python 變數語法的標籤組成。在 ASCII 中，這包含大寫和小寫字母 A 到 Z、底線 _，以及除了第一個字元之外的數字 0 到 9。

在版本 0.6 中新增。

版本 1.2 變更：新增了建置器的名稱和前綴。

警告

此指令旨在僅控制文件內容。它無法控制章節、標籤等等。

表格

使用 reStructuredText 表格，即以下任一種

table 指令用作 grid 和 simple 語法的可選包裝器。

它們在 HTML 輸出中運作良好，但將表格渲染為 LaTeX 很複雜。請查看 latex_table_style。

版本 1.6 變更：來自包含複雜內容（例如多個段落、引用區塊、清單、文字區塊）的格線表格的合併儲存格（多列、多行、兩者）將正確渲染為 LaTeX 輸出。

.. tabularcolumns:: 欄位 規格

此指令僅影響來源中下一個表格的 LaTeX 輸出。必要引數是欄位規格（在 LaTeX 慣用語中稱為「對齊前導碼」）。請參閱 LaTeX 文件，例如 wiki 頁面，以了解此類欄位規格的基本知識。

在版本 0.3 中新增。

注意

tabularcolumns 與表格指令的 :widths: 選項衝突。如果兩者都指定，:widths: 選項將被忽略。

Sphinx 將使用 longtable 渲染超過 30 列的表格。除了 l、r、c 和 p{width} 欄位規範符號之外，還可以使用的 \X{a}{b} (版本 1.5 新增)，它將欄位寬度設定為總行寬的 a/b 分數，以及 \Y{f} (版本 1.6 新增)，其中 f 是十進制：例如 \Y{0.2} 表示欄位將佔用行寬的 0.2 倍。

當此指令用於最多 30 列的表格時，Sphinx 將使用 tabulary 渲染它。然後可以使用特定的欄位類型 L (靠左)、R (靠右)、C (置中) 和 J (左右對齊)。它們具有 p{width} 的效果（即每個儲存格都是 LaTeX \parbox），具有指定的內部文字對齊方式和自動計算的 width。

警告

  • 包含類似清單的元素（例如物件描述、引用區塊或任何種類的清單）的儲存格與 LRCJ 欄位類型不相容。然後，欄位類型必須是具有明確 width 的 p{width}（或 \X{a}{b} 或 \Y{f}）。

  • 文字區塊完全不適用於 tabulary。Sphinx 將退回到 tabular 或 longtable 環境，並產生合適的欄位規格。

在沒有 tabularcolumns 指令的情況下，對於最多 30 列且沒有上述警告中描述的問題儲存格的表格，Sphinx 會使用 tabulary 和每個欄位的 J 欄位類型。

版本 1.6 變更：以前，使用 L 欄位類型（文字靠左對齊）。若要恢復為此狀態，請在 LaTeX 前導碼中包含 \newcolumntype{T}{L}，實際上 Sphinx 使用 T 並預設將其設定為 J 的別名。

提示

tabulary 的常見問題是內容很少的欄位看起來會被「擠壓」。可以將例如 \setlength{\tymin}{40pt} 新增到 LaTeX 前導碼中，以確保最小欄位寬度為 40pt，tabulary 的預設值 10pt 太小。

提示

若要強制使用 LaTeX longtable 環境，請將 longtable 作為 :class: 選項傳遞給 table、csv-table 或 list-table。針對其他表格，請使用 rst-class。

數學

數學的輸入語言是 LaTeX 標記。這是純文字數學符號的事實標準，並且具有在建置 LaTeX 輸出時無需進一步翻譯的額外優點。

請記住，當您將數學標記放在 autodoc 讀取的 Python 文件字串中時，您必須將所有反斜線加倍，或使用 Python 原始字串 (r"raw")。

.. math::

用於顯示數學的指令（數學佔用整行）。

該指令支援多個方程式，應以空白行分隔

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

此外，每個單一方程式都設定在 split 環境中，這表示您可以在方程式中有多個對齊的行，在 & 處對齊，並以 \\ 分隔

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

如需更多詳細資訊，請查看 AmSMath LaTeX 套件的文件。

當數學只有一行文字時，也可以作為指令引數給定

.. math:: (a + b)^2 = a^2 + 2ab + b^2

選項

:class: 類別 名稱 (類別 名稱 的 清單，以空格分隔)

指派 類別屬性。這是 通用選項。

:name: 標籤 (文字)

可以使用 ref 參照的隱含目標名稱。這是 通用選項。

:label: 標籤 (文字)

通常，方程式不會編號。如果您希望方程式取得編號，請使用 label 選項。給定此選項時，它會為方程式選取一個內部標籤，可以透過該標籤進行交叉參照，並導致發出方程式編號。請參閱 eq 以取得範例。編號樣式取決於輸出格式。

:no-wrap:

防止給定的數學在數學環境中換行。當您給定此選項時，您必須自行確保數學已正確設定。例如

.. math::
   :no-wrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

版本 8.2 變更：指令選項 :nowrap: 已重新命名為 :no-wrap:。

先前的名稱已保留為別名，但在未來版本的 Sphinx 中將被棄用和移除。

另請參閱

Sphinx 中 HTML 輸出的數學支援

HTML 建置器的數學渲染選項。

latex_engine

說明如何組態 LaTeX 建置器以支援數學標記中的 Unicode 文字。

語法產生式顯示

特殊標記可用於顯示形式文法的產生式。標記很簡單，並未嘗試模擬 BNF（或任何衍生形式）的所有層面，但提供了足夠的功能，可以以一種方式顯示上下文無關文法，從而使符號的用法呈現為指向符號定義的超連結。有以下指令

.. productionlist:: [production_group]

此指令用於封閉一組產生式。每個產生式都在單行上給定，並由一個名稱組成，該名稱與後面的定義以冒號分隔。如果定義跨越多行，則每個繼續行都必須以冒號開頭，該冒號放置在與第一行相同的欄位中。productionlist 指令引數中不允許有空白行。

可選的 production_group 指令引數用於區分屬於不同文法的不同組產生式清單。因此，具有相同 production_group 的多個產生式清單在相同的範圍內定義規則。這也可以用於跨具有相同 production_group 的多個 productionlist 指令來分割長文法或複雜文法的描述。

定義可以包含標記為已解譯文字的符號名稱（例如，「sum ::= `integer` "+" `integer`」），以產生對這些符號的產生式的交叉參照。此類交叉參照隱含地參照來自目前群組的產生式。若要參照來自另一個文法的產生式，符號名稱必須以群組名稱和冒號為前綴，例如「other-group:sum」。如果符號的群組不應顯示在產生式中，則可以使用波浪符號為其加上前綴，例如「~other-group:sum」。若要參照來自未命名文法的產生式，符號應以冒號為前綴，例如「:sum」。產生式中不會執行進一步的 reStructuredText 剖析，因此特殊字元（*、| 等）不需要逸出。

符號產生式可以使用 token 角色在產生式清單之外進行交叉參照。如果您使用了 production_group 引數，則符號名稱必須以群組名稱和冒號為前綴，例如「my_group:sum」而不是僅僅「sum」。標準 交叉參照修飾符 可以與 :token: 角色一起使用，例如自訂連結文字和使用波浪符號 (~) 隱藏群組名稱。

以下是取自 Python 參考手冊的範例

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

註腳