`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 引用，以及其他缺失的对象引用，以链接到其他文档。
默认情况下，映射文件被假定为与文档的其余部分位于同一位置；但是，也可以单独指定映射文件的位置，例如，如果文档应该在没有 Internet 访问的情况下可构建。

配置¶

要使用 Intersphinx 链接，请将 'sphinx.ext.intersphinx' 添加到您的 extensions 配置值，并使用这些配置值来激活链接

intersphinx_mapping¶

类型:: dict[str, tuple[str, tuple[str, tuple[str | None, ...]]]]
默认值:: {}

此配置值包含应在此文档中链接到的其他项目的位置和名称。

目标位置的相对本地路径被视为相对于构建文档的根目录，而清单位置的相对本地路径被视为相对于源目录。

当获取远程清单文件时，代理设置将从 $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.pythonlang.cn/3', None)}

这将从 Internet 下载相应的 objects.inv 文件，并生成指向给定 URI 下页面的链接。下载的清单缓存在 Sphinx 环境中，因此每当您进行完整重建时，都必须重新下载它。

第二个示例，展示了第二个元组项的非 None 值的含义

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

这将从源目录中的 python-inv.txt 读取清单，但仍会生成指向 https://docs.pythonlang.cn/3 下页面的链接。当新对象添加到 Python 文档时，您需要更新清单文件。

清单的多个目标

1.3 版本新增。

可以为每个清单指定备用文件。可以为第二个清单元组项提供一个元组，如下例所示。这将读取清单，遍历（第二个）元组项，直到第一次成功获取。此操作的主要用例是为主要清单的服务器停机指定镜像站点

intersphinx_mapping = {'python': ('https://docs.pythonlang.cn/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 的文档或继承其文档字符串的项目，然后将使用 'astropy' 键配置其 intersphinx_mapping，指向 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 不是整个响应下载的时间限制；而是如果服务器在 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.pythonlang.cn/3/objects.inv

在基本身份验证下使用带有清单文件的 Intersphinx¶

Intersphinx 支持像这样的基本身份验证

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

生成链接时，用户名和密码将从 URL 中剥离。

sphinx.ext.intersphinx – 链接到其他项目的文档¶

配置¶

显式引用外部对象¶

显示 Intersphinx 映射文件的所有链接¶

在基本身份验证下使用带有清单文件的 Intersphinx¶

`sphinx.ext.intersphinx` – 链接到其他项目的文档¶