交叉參照

Sphinx 最有用的功能之一是通過語義交叉參照角色建立自動交叉參照。例如，交叉參照到物件描述，例如 :func:`spam`，將會建立一個連結，連到 spam() 的文件位置，適用於每個輸出格式（HTML、PDF、ePUB 等）。

語法

Sphinx 支援各種交叉參照角色，以建立連到文件中的其他元素的連結。一般來說，寫入 :role:`target` 會建立一個連結，連到類型由角色指示且名為 target 的物件。連結的文字取決於角色，但通常與 target 相同或相似。

行為可以通過以下方式修改

  • 自訂連結文字： 您可以使用與 reStructuredText 外部連結 相同的標記法來明確指定連結文字：:role:`custom text <target>` 將參考 target 並顯示自訂文字作為連結的文字。

  • 抑制連結： 以驚嘆號（!）作為前綴可以防止建立連結，但會保留角色的視覺輸出。

    例如，寫入 :py:func:`!target` 會顯示 target()，而不會產生連結。

    這對於連結目標不存在的情況很有幫助；例如，描述已移除功能的變更日誌條目，或是不支援 intersphinx 的第三方函式庫。抑制連結可以防止在 nitpicky 模式下發出警告。

  • 修改的領域參考： 當 參考領域物件 時，波浪符號 ~ 前綴會將連結文字縮短為目標的最後一個組件。例如，:py:meth:`~queue.Queue.get` 將參考 queue.Queue.get，但只會顯示 get 作為連結文字。

    在 HTML 輸出中，連結的 title 屬性（例如，在滑鼠懸停時顯示為工具提示）將始終是完整的目標名稱。

交叉參照物件

這些角色在其各自的領域中描述

交叉參照任意位置

:ref:

為了支援交叉參照到任何文件中的任意位置，使用了標準的 reStructuredText 標籤。為了使此功能正常運作，標籤名稱在整個文件中必須是唯一的。您可以使用兩種方式參考標籤

  • 如果您將標籤直接放在章節標題之前，則可以使用 :ref:`label-name` 參考它。例如

    .. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

    :ref: 角色隨後將產生一個連到該章節的連結，連結標題為「要交叉參照的章節」。當章節和參考位於不同的來源檔案中時，這也同樣有效。

    自動標籤也適用於圖。例如

    .. _my-figure:

.. figure:: whatever

   Figure caption

    在這種情況下，參考 :ref:`my-figure` 將插入對圖的參考，連結文字為「圖說文字」。

    這同樣適用於使用 table 指令給定明確標題的表格。

  • 未放置在章節標題之前的標籤仍然可以被參考，但您必須使用以下語法為連結提供明確的標題：:ref:`Link title <label-name>`。

注意

參考標籤必須以底線開頭。參考標籤時，必須省略底線（請參閱以上範例）。

建議使用 ref 而不是標準的 reStructuredText 章節連結（例如 `Section title`_），因為它可以跨檔案工作，當章節標題變更時會發出警告（如果錯誤），並且適用於所有支援交叉參照的建構器。

交叉參照文件

在版本 0.6 中新增。

還有一種方法可以直接連結到文件

:doc:

連結到指定的文件；文件名稱可以使用絕對或相對方式指定。例如，如果參考 :doc:`parrot` 出現在文件 sketches/index 中，則連結會參考 sketches/parrot。如果參考是 :doc:`/people` 或 :doc:`../people`，則連結會參考 people。

如果沒有給定明確的連結文字（像往常一樣：:doc:`Monty Python members </people>`），則連結標題將會是給定文件的標題。

參考可下載檔案

在版本 0.6 中新增。

:download:

這個角色讓您可以連結到來源樹中的檔案，這些檔案不是可以檢視的 reStructuredText 文件，而是可以下載的檔案。

當您使用這個角色時，被參考的檔案會自動標記為包含在建構時的輸出中（顯然，僅適用於 HTML 輸出）。所有可下載的檔案都放在輸出目錄的 _downloads/<unique hash>/ 子目錄中；重複的檔案名稱會被處理。

範例

See :download:`this example script <../example.py>`.

給定的檔案名稱通常相對於目前來源檔案所在的目錄，但如果是絕對路徑（以 / 開頭），則會被視為相對於頂層來源目錄。

example.py 檔案將被複製到輸出目錄，並產生一個指向它的合適連結。

為了不顯示不可用的下載連結，您應該將具有此角色的整個段落包裝起來

.. only:: builder_html

   See :download:`this example script <../example.py>`.

依圖號交叉參照圖

在版本 1.3 中新增。

在版本 1.5 中變更： numref 角色也可以參考章節。並且 numref 允許使用 {name} 作為連結文字。

:numref:

連結到指定的圖、表格、程式碼區塊和章節；使用了標準的 reStructuredText 標籤。當您使用這個角色時，它將插入對圖的參考，連結文字為其圖號，例如「圖 1.1」。

如果給定明確的連結文字（像往常一樣：:numref:`Image of Sphinx (Fig. %s) <my-figure>`），則連結標題將作為參考的標題。作為佔位符，%s 和 {number} 會被圖號取代，而 {name} 則會被圖說文字取代。如果沒有給定明確的連結文字，則會使用 numfig_format 設定作為回退預設值。

如果 numfig 為 False，則圖不會編號，因此這個角色插入的不是參考，而是標籤或連結文字。

交叉參照其他感興趣的項目

以下角色可能會建立交叉參照，但不會參考物件

:confval:

組態值或設定。會產生索引條目。如果存在，也會產生一個連到相符的 confval 指令的連結。

:envvar:

環境變數。會產生索引條目。如果存在，也會產生一個連到相符的 envvar 指令的連結。

:token:

語法符號的名稱（用於在 productionlist 指令之間建立連結）。

:keyword:

Python 中關鍵字的名稱。如果存在，這會建立一個連到具有該名稱的參考標籤的連結。

:option:

可執行程式的命令列選項。如果存在，這會產生一個連到 option 指令的連結。

以下角色會建立一個交叉參照，連到 詞彙表 中的術語

:term:

參考詞彙表中的術語。詞彙表是使用包含術語和定義的定義列表的 glossary 指令建立的。它不一定需要與 term 標記位於同一個檔案中，例如，Python 文件在 glossary.rst 檔案中就有一個全域詞彙表。

如果您使用詞彙表中未說明的術語，您將在建構期間收到警告。

這個角色也支援來自一般交叉參照語法的 自訂連結文字。

交叉參照任何事物

:any:

在版本 1.3 中新增。

這個方便的角色會盡力為其參考文字尋找有效的目標。

  • 首先，它會嘗試標準交叉參照目標，這些目標將由 doc、ref 或 option 參考。

    擴充功能新增到標準領域的自訂物件（請參閱 Sphinx.add_object_type()）也會被搜尋。

  • 然後，它會在所有載入的領域中尋找物件（目標）。領域決定比對必須有多精確。例如，在 Python 領域中，:any:`Builder` 的參考將會比對 sphinx.builders.Builder 類別。

如果找不到目標或找到多個目標，將會發出警告。如果找到多個目標，您可以將「any」變更為特定的角色。

這個角色非常適合設定 default_role。如果您這樣做，您可以編寫交叉參照，而無需大量的標記額外負荷。例如，在這個 Python 函式文件中

.. function:: install()

   This function installs a `handler` for every signal known by the
   `signal` module.  See the section `about-signals` for more information.

可能會參考詞彙表術語（通常是 :term:`handler`）、Python 模組（通常是 :py:mod:`signal` 或 :mod:`signal`）和章節（通常是 :ref:`about-signals`）。

any 角色也與 intersphinx 擴充功能一起運作：當找不到本機交叉參照時，也會搜尋 intersphinx 清單的所有物件類型。