`sphinx.ext.intersphinx` -- 链接到其他文档¶

在 0.5 版本加入.

本扩展可以生成指向外部项目中文档对象的链接，可以通过 external 角色显式地链接，也可以作为任何其他交叉引用的后备兜底解析方案。

用于后备解析的用法很简单：每当Sphinx遇到当前文档集中没有匹配目标的交叉引用时，它会在 intersphinx_mapping 中配置的外部文档集中查找目标。像 :py:class:`zipfile.ZipFile` 这样的引用可以链接到ZipFile类的Python文档，而无需您指定它的确切位置。

使用 external 角色时，您可以强制查找任何外部项目，并可选择特定的外部项目。像 :external:ref:`comparison manual <comparisons>` 这样的链接可以链接到任何已配置的外部项目中的标签“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，可以是本地路径或httpuri。 inventory 指示可以在何处找到清单文件：它可以是“None”（一个 objects.inv 文件与URI位于同一位置）或另一个本地路径或完整的HTTP URI指向清单文件。

唯一标识符可以在 external 角色中使用，因此可以清楚地知道目标属于哪个intersphinx集。像 :external+python:ref:`comparison manual <comparisons>` 这样的链接可以链接到文档集“python”中的标签“comparisons”，如果它存在。

举例

要在Python标准库文档中添加指向模块和对象的链接，请使用：

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

这将下载相应的 objects.inv 从Internet上创建文件并生成指向给定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 版本加入.

可以为每个库存指定替代文件。可以为第二个inventory tuple项提供一个元组，如下例所示。这将读取遍历（第二个）元组项的库存，直到第一次成功获取。用于指定主资源清册服务器停机时间的镜像站点的主要使用情形：

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 文档或继承其文档字符串的项目将使用 'astropy' 键配置其 intersphinx_mapping，指向 astropy 的 objects.inv。例如：

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

intersphinx_cache_limit¶

类型:: int
默认:: 5 (five days)

缓存远程库存的最大天数。将其设置为负值以无限期缓存库存。

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:*，或
简单的通配符 *。

当非 external 交叉引用由 intersphinx 解析时，如果它与此列表中的某个规范匹配，则跳过解析。

例如，使用 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:std:doc:`installation`，例如：: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`。

显示内部sphinx映射文件的所有链接¶

要显示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 -- 链接到其他文档¶

配置¶

显式引用外部对象¶

显示内部sphinx映射文件的所有链接¶

在基本授权下使用Intersphinx和库存文件¶

`sphinx.ext.intersphinx` -- 链接到其他文档¶