`sphinx.ext.intersphinx` – 連結到其他專案的文件¶

在版本 0.5 中新增。

此擴充功能可以產生連結到外部專案中物件的文件，可以透過 external 角色明確地產生，或者作為任何其他跨參照的回退解析。

回退解析的使用方式很簡單：每當 Sphinx 遇到在目前文件集中沒有相符目標的跨參照時，它會在 intersphinx_mapping 中設定的外部文件集中尋找目標。像 :py:class:`zipfile.ZipFile` 這樣的參照就可以連結到 ZipFile 類別的 Python 文件，而無需您明確指定它的確切位置。

當使用 external 角色時，您可以強制查詢任何外部專案，並且可選擇性地查詢特定的外部專案。像 :external:ref:`comparison manual <comparisons>` 這樣的連結將會連結到任何已設定的外部專案中的標籤 “comparisons”（如果存在），而像 :external+python:ref:`comparison manual <comparisons>` 這樣的連結將只會連結到文件集 “python” 中的標籤 “comparisons”（如果存在）。

在幕後，其運作方式如下

每個 Sphinx HTML 建置都會建立一個名為 objects.inv 的檔案，其中包含從物件名稱到相對於 HTML 集根目錄的 URI 的對應。
使用 Intersphinx 擴充功能的專案可以在 intersphinx_mapping 設定值中指定此類對應檔案的位置。然後，此對應將用於解析 external 參照，以及其他遺失的物件參照，以連結到其他文件。
預設情況下，對應檔案會被假定與其餘文件位於相同位置；但是，也可以個別指定對應檔案的位置，例如，如果文件應該在沒有網路連線的情況下也能建置。

配置¶

要使用 Intersphinx 連結，請將 'sphinx.ext.intersphinx' 新增到您的 extensions 設定值，並使用這些設定值來啟用連結

intersphinx_mapping¶

類型:: dict[str, tuple[str, tuple[str, tuple[str | None, ...]]]]
預設:: {}

此設定值包含應在此文件中連結的其他專案的位置和名稱。

目標位置的相對本機路徑是相對於已建置文件的根目錄，而庫存位置的相對本機路徑是相對於原始碼目錄。

當擷取遠端庫存檔案時，Proxy 設定將從 $HTTP_PROXY 環境變數中讀取。

格式

在版本 1.0 中新增。

一個字典，將唯一識別碼對應到一個元組 (target, inventory)。每個 target 都是外部 Sphinx 文件集的基本 URI，可以是本機路徑或 HTTP URI。 inventory 指示庫存檔案可以在哪裡找到：它可以是 None（與基本 URI 位於相同位置的 objects.inv 檔案）或另一個本機檔案路徑或庫存檔案的完整 HTTP URI。

唯一識別碼可以用於 external 角色中，以便清楚地知道目標屬於哪個 intersphinx 集。像 :external+python:ref:`comparison manual <comparisons>` 這樣的連結將會連結到文件集 “python” 中的標籤 “comparisons”（如果存在）。

範例

要新增連結到 Python 標準函式庫文件中的模組和物件，請使用

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

這將從網際網路下載對應的 objects.inv 檔案，並產生連結到給定 URI 下頁面的連結。下載的庫存會快取在 Sphinx 環境中，因此每當您執行完整重建時都必須重新下載。

第二個範例，顯示第二個元組項目的非 None 值的含義

intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                  'python-inv.txt')}

這將從原始碼目錄中的 python-inv.txt 讀取庫存，但仍然產生連結到 https://docs.python.org/3 下頁面的連結。當新物件新增到 Python 文件時，您有責任更新庫存檔案。

庫存的多個目標

在版本 1.3 中新增。

可以為每個庫存指定替代檔案。可以為第二個庫存元組項目提供一個元組，如下列範例所示。這將讀取庫存，並迭代（第二個）元組項目，直到第一次成功擷取。這樣做的主要使用案例是為主要庫存的伺服器停機指定鏡像站點

intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                  (None, 'python-inv.txt'))}

對於一組在本地編輯和測試然後一起發布的書籍，首先嘗試本機庫存檔案以在發布前檢查參照可能會很有幫助

intersphinx_mapping = {
    'otherbook':
        ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
            ('../../otherbook/build/html/objects.inv', None)),
}

intersphinx_resolve_self¶

類型:: str
預設:: ''

如果提供，intersphinx_resolve_self 會覆寫 intersphinx 的解析機制，以解析對目前專案的所有參照，而不是外部參照。當文件在專案之間共用時，這很有用，「上游」或「父」專案在其文件中使用 intersphinx 樣式的參照。例如，像 Astropy 這樣的專案可能會設定

intersphinx_resolve_self = 'astropy'

重新使用 Astropy 的文件或繼承其 docstring 的專案，然後將其 intersphinx_mapping 配置為具有 'astropy' 鍵，指向 astropy 的 objects.inv。例如

intersphinx_mapping = {
    'astropy': ('https://docs.astropy.org/en/stable/', None),
}

intersphinx_cache_limit¶

類型:: int
預設:: 5 (五天)

快取遠端庫存的最大天數。將此設定為負值以無限期快取庫存。

intersphinx_timeout¶

類型:: int | float | None
預設:: None

逾時的秒數。使用 None 表示沒有逾時。

注意

逾時不是整個回應下載的時間限制；相反地，如果伺服器在 timeout 秒內沒有發出回應，則會引發例外狀況。

intersphinx_disabled_reftypes¶

類型:: Sequence[str]
預設:: ['std:doc']

在版本 4.3 中新增。

在版本 5.0 中變更：將預設值從空列表變更為 ['std:doc']。

字串列表，可以是

網域中特定參照類型的名稱，例如 std:doc、py:func 或 cpp:class,
網域的名稱和萬用字元，例如 std:*、py:* 或 cpp:*，或者
只是萬用字元 *。

當 intersphinx 正在解析非 external 跨參照時，如果它符合此列表中的其中一個規格，則跳過解析。

例如，使用 intersphinx_disabled_reftypes = ['std:doc']，跨參照 :doc:`installation` 將不會嘗試由 intersphinx 解析，但 :external+otherbook:doc:`installation` 將會嘗試在 intersphinx_mapping 中名為 otherbook 的庫存中解析。同時，例如在 Python 宣告中產生的所有跨參照仍將嘗試由 intersphinx 解析。

如果 * 在網域列表中，則 intersphinx 將不會解析任何非 external 參照。

明確地參考外部物件¶

Intersphinx 擴充功能提供以下角色。

:external:¶

在版本 4.4 中新增。

使用 Intersphinx 僅在外部專案中執行查找，而不是在目前專案中。 Intersphinx 仍然需要知道您想要尋找的物件類型，因此此角色的一般形式是撰寫跨參照，就好像物件在目前專案中一樣，然後在其前面加上 :external。然後是兩種形式

:external:domain:reftype:`target`，例如 :external:py:class:`zipfile.ZipFile`，或
:external:reftype:`target`，例如 :external:doc:`installation`。使用此簡寫，網域假定為 std。

如果您想將查找限制為特定的外部專案，則專案的鍵（如 intersphinx_mapping 中指定）也會新增以取得兩種形式

:external+invname:domain:reftype:`target`，例如 :external+python:py:class:`zipfile.ZipFile`，或
:external+invname:reftype:`target`，例如 :external+python:doc:`installation`。

顯示 Intersphinx 對應檔的所有連結¶

要顯示 Intersphinx 對應檔的所有 Intersphinx 連結及其目標，請執行 python -m sphinx.ext.intersphinx url-or-path。這在尋找文件專案中損壞的 Intersphinx 連結的根本原因時很有幫助。以下範例列印 Python 文件的 Intersphinx 對應

$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv

在基本授權下使用 Intersphinx 與庫存檔案¶

Intersphinx 支援像這樣的基本授權

intersphinx_mapping = {'python': ('https://user:[email protected]/3',
                                  None)}

在產生連結時，使用者名稱和密碼將從 URL 中移除。

sphinx.ext.intersphinx – 連結到其他專案的文件¶

配置¶

明確地參考外部物件¶

顯示 Intersphinx 對應檔的所有連結¶

在基本授權下使用 Intersphinx 與庫存檔案¶

`sphinx.ext.intersphinx` – 連結到其他專案的文件¶