sphinx.ext.intersphinx --链接到其他项目的文档¶
Added in version 0.5.
此扩展可以生成指向外部项目中对象的文档的链接，可以通过 external 角色，或作为任何其他交叉引用的备用解决方案。
回退解析的用法很简单：每当Sphinx遇到在当前文档集中没有匹配目标的交叉引用时，它就会在 intersphinx_mapping 。像这样的引用 :py:class:`zipfile.ZipFile 然后，`就可以链接到zipfile类的Python文档，而不必指定它的确切位置。
在使用 external 角色，您可以强制查找任何外部项目，也可以选择查找特定的外部项目。像这样的链接 :external:ref:`comparison manual <comparisons> 然后，将链接到任何已配置的外部项目中的标签“比较”(如果存在)，以及如下链接 `comparison manual <comparisons>` `只会链接到文档集python中的比较标签，如果存在的话。
幕后工作如下：
每个sphinx html构建创建一个名为
objects.inv它包含从对象名到相对于HTML集根目录的URI的映射。使用Intersphinx扩展的项目可以指定此类映射文件在
intersphinx_mapping配置值。然后将使用映射来解析这两个external引用，否则还会将对对象的引用遗漏到指向其他文档的链接中。默认情况下，假定映射文件与文档的其余部分位于同一位置；但是，也可以单独指定映射文件的位置，例如，如果文档可以在没有Internet访问的情况下构建。
配置¶
要使用Intersphinx链接，请添加 'sphinx.ext.intersphinx' 对你 extensions 配置值，并使用这些配置值激活链接：
- intersphinx_mapping¶
此配置值包含本文档中应链接到的其他项目的位置和名称。
目标位置的相对本地路径被视为相对于已构建文档的基础，而库存位置的相对本地路径被视为相对于源目录。
获取远程清单文件时，代理设置将从
$HTTP_PROXY环境变量。Format
Added in version 1.0.
将唯一标识符映射到元组的字典
(target, inventory)。每个人target是外来Sphinx文档集的基URI，可以是本地路径或HTTP URI。这个inventory指示可以找到清单文件的位置：可以是None(一个objects.inv与基本URI位于相同位置的文件)或其他本地文件路径或清单文件的完整HTTP URI。该唯一标识符可用于
external角色，这样就可以清楚地知道目标属于哪个intersphinx集合。像这样的链接external:python+ref:`comparison manual <comparisons>如果有，`会链接到文档集python中的比较标签。Example
要添加到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文档中时，由您来更新清单文件。库存的多个目标
Added in version 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)), }
此配置值的旧格式
自 6.2 版本弃用.
小心
这是Sphinx 1.0之前使用的格式。它已弃用，将在Sphinx 8.0中删除。
将URI映射到
None或URI。这些键是外部sphinx文档集的基URI，可以是本地路径或HTTP URI。这些值指示可以在何处找到库存文件：它们可以None（与基URI位于同一位置）或其他本地或HTTP URI。例子：
intersphinx_mapping = {'https://docs.python.org/': None}
- intersphinx_cache_limit¶
缓存远程清单的最大天数。默认值为
5意思是五天。将此值设置为负值以无限时间缓存库存。
- intersphinx_timeout¶
超时的秒数。默认值为
None，表示不超时。备注
超时不是整个响应下载的时间限制；相反，如果服务器在超时秒内未发出响应，则会引发异常。
- intersphinx_disabled_reftypes¶
Added in version 4.3.
在 5.0 版本发生变更: 将缺省值从空列表更改为
['std:doc']。字符串列表为以下任一项：
域中特定引用类型的名称，例如，
std:doc，py:func，或cpp:class，域名和通配符，例如，
std:*，py:*，或cpp:*，或简单的通配符
*。
缺省值为
['std:doc']。当一个非 -
externalIntersphinx正在解析交叉引用，如果与此列表中的某个规范匹配，则跳过解析。例如，使用
intersphinx_disabled_reftypes = ['std:doc']相互参照:doc:`installation不会尝试由Intersphinx解析`，但是:external+otherbook:doc:`installation将尝试在名为的清单中解析`otherbook在……里面intersphinx_mapping。同时，仍将尝试由Intersphinx解析在例如Python声明中生成的所有交叉引用。如果
*在域列表中，则没有空域 -external引用将由Intersphinx解决。
显式引用外部对象¶
Intersphinx扩展提供了以下角色。
- :external:¶
Added in version 4.4.
使用Intersphinx仅在外部项目中执行查找，而不在当前项目中执行。Intersphinx仍然需要知道您想要查找的对象的类型，因此此角色的一般形式是编写交叉引用，就像该对象在当前项目中一样，但然后在它前面加上
:external。这两种形式就是:external:domain:reftype:`target，例如， `zipfile.ZipFile``，或:external:reftype:`target，例如， `installation` 。使用此速记时，假设域为 ``std` 。
如果要将查找限制到特定的外部项目，则该项目的键，如
intersphinx_mapping也被添加，以获得这两个表单
显示Intersphinx映射文件的所有链接¶
要显示Interphinx映射文件的所有Interphinx链接及其目标，请运行 python -msphinx.ext.intersphinx url-or-path . 在文档项目中搜索中断Interphinx链接的根本原因时，这很有用。下面的示例打印了python 3文档的phinx映射：
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv