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¶
此配置值包含应在此文档中链接到的其他项目的位置和名称。
目标位置的相对本地路径相对于构建文档的基目录，而清单位置的相对本地路径相对于源目录。
在获取远程清单文件时，代理设置将从
$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_cache_limit¶
缓存远程清单的最长时间（以天为单位）。默认值为
5，即五天。将其设置为负值以无限期缓存清单。
- intersphinx_timeout¶
超时时间（以秒为单位）。默认值为
None，表示不超时。注意
超时不是整个响应下载的时间限制；相反，如果服务器在超时秒内未发出响应，则会引发异常。
- intersphinx_disabled_reftypes¶
版本 4.3 中新增。
版本 5.0 中更改： 将默认值从空列表更改为
['std:doc']。一个字符串列表，可以是
域中特定引用类型的名称，例如
std:doc、py:func或cpp:class，域的名称和通配符，例如
std:*、py:*或cpp:*，或只是一个通配符
*。
默认值为
['std:doc']。当 intersphinx 解析非
external交叉引用时，如果它与列表中的一个规范匹配，则跳过解析。例如，使用
intersphinx_disabled_reftypes = ['std:doc']，交叉引用:doc:`installation`将不会尝试通过 intersphinx 解析，但:external+otherbook:doc:`installation`将尝试在名为otherbook的清单中解析，该清单在intersphinx_mapping中定义。同时，例如在 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 -msphinx.ext.intersphinx url-or-path。这在搜索文档项目中损坏的 Intersphinx 链接的根本原因时非常有用。以下示例打印 Python 3 文档的 Intersphinx 映射
$ python -m sphinx.ext.intersphinx https://docs.pythonlang.cn/3/objects.inv