sphinx.ext.intersphinx —— 链接到其他项目文档¶
0.5 新版功能.
此插件可以生成到外部项目中对象的文档的链接，要么明确地通过 external 角色，要么作为任何其他交叉引用的备用解析。
回退解析的用法很简单：每当 Sphinx 遇到交叉引用，该引用在当前文档集中没有匹配的目标，它就会在 intersphinx_mapping 中配置的外部文档集中寻找目标。像 :py:class:`zipfile.ZipFile` 可以链接到 Python 文档的 ZipFile 类，而不必指定它的确切位置。
当使用 external 角色时，你可以强制查找到任何外部项目，也可以选择查找到特定的外部项目。如果存在 :external:ref:`comparison manual <comparisons>` 这样的链接，则会链接到 label “comparisons” ，如果存在 :external+python:ref:`comparison manual <comparisons>` 这样的链接，则只会链接到文档集 “python” 中的 label “comparisons”。
在幕后，它的工作原理如下：
每次 Sphinx HTML 构建都会创建名为
objects.inv的文件，它包含了相对于 HTML 集合 root 的从对象名称到 URI 的映射。使用 Intersphinx 插件的项目可以在
intersphinx_mapping配置值中指定这样的映射文件的位置。然后，这个映射将被用来解析external引用，以及其他文档链接中缺少的对象引用。默认情况下，映射文件被认为与文档的其他部分位于相同的位置；然而，映射文件的位置也可以单独指定，例如，如果文档应该在没有互联网接入的情况下构建。
配置¶
要使用 Intersphinx 链接，请将 'sphinx.ext.intersphinx' 添加到您的 extensions 配置值中，并使用这些配置值来激活链接：
- intersphinx_mapping¶
这个配置值包含应该在本文档中链接到的其他项目的位置和名称。
目标位置的相对本地路径被认为是相对于构建文档的基础，而库存（inventory）位置的相对本地路径被认为是相对于源目录。
当获取远程库存文件时，代理设置将从环境变量
$HTTP_PROXY中读取。此配置值的旧格式
这是 Sphinx 1.0 之前使用的格式。它仍然是公认的。
将 URI 映射到
None或 URI 的字典。键是外部 Sphinx 文档集的 base URI，可以是本地路径或 HTTP URI。这些值指示库存文件可以在哪里找到：它们可以是None（与 base URI 在同一位置）或其他本地或 HTTP URI。新格式的配置值
1.0 新版功能.
将唯一标识符映射到元组
(target, inventory)的字典。每个target都是外部 Sphinx 文档集的 base URI，可以是本地路径或 HTTP URI。inventory表示库存文件可以在哪里找到：它可以是None（在与 base URI 相同的位置的objects.inv文件）或另一个本地文件路径或完整的 HTTP URI 到库存文件。可以在
external角色中使用的唯一标识符，这样就可以清楚地知道目标是属于哪个 intersphinx 设置的。像external:python+ref:`comparison manual <comparisons>`这样的链接将链接到文档集 “python” 中的 label “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_cache_limit¶
缓存远程库存的最大天数。默认值是
5，即 5 天。将此设置为负值，以缓存无限时间的库存。
- intersphinx_timeout¶
超时的秒数。默认值为
None，表示不超时。备注
timeout 不是对整个响应下载的时间限制；相反，如果服务器没有针对超时时间发出响应，则会引发异常。
- intersphinx_disabled_reftypes¶
4.3 新版功能.
字符串列表可以是：
域中特定引用类型的名称，例如
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:domain:reftype:`target`，如:external:py:class:`zipfile.ZipFile`或:external:reftype:`target`，如:external:doc:`installation`。
如果你想限制查找到特定的外部项目，那么项目的键，如指定
intersphinx_mapping，也被添加，以获得两个形式:external+invname:domain:reftype:`target`, e.g.,:external+python:py:class:`zipfile.ZipFile`, or:external+invname:reftype:`target`, e.g.,:external+python:doc:`installation`.
显示 Intersphinx 映射文件的所有链接¶
运行 python -msphinx.ext.intersphinx url-or-path 命令，显示 Intersphinx 映射文件的所有链接和它们的目标。这在文档项目中搜索 Intersphinx 链接中断的根本原因时很有帮助。下面的例子打印了 Python 3 文档中的 Intersphinx 映射：
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv