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它包含一个从对象名称到URI的映射，该URI相对于HTML集的根。使用Intersphinx扩展的项目可以指定此类映射文件在
intersphinx_mapping配置值。然后将使用映射来解析这两个external引用，否则还会将对对象的引用遗漏到指向其他文档的链接中。默认情况下，假定映射文件与文档的其余部分位于相同的位置；但是，也可以单独指定映射文件的位置，例如，如果文档应该可以在没有互联网访问的情况下构建。
配置¶
要使用Intersphinx链接，请添加 'sphinx.ext.intersphinx' 致您的 extensions 配置值，并使用这些配置值激活链接：
- intersphinx_mapping¶
- 类型:
dict[str, tuple[str, tuple[str, tuple[str | None, ...]]]]- 默认:
{}
此配置值包含本文档中应链接到的其他项目的位置和名称。
目标位置的相对本地路径被视为相对于已构建文档的基础，而库存位置的相对本地路径被视为相对于源目录。
获取远程库存文件时，将从
$HTTP_PROXY环境变量。Format
Added in version 1.0.
将唯一标识符映射到元组的词典
(target, inventory)。每个target是外来Sphinx文档集的基本URI，可以是本地路径或HTTP URI。这个inventory指示可以找到清单文件的位置：它可以在None(一个objects.inv与基本URI位于相同位置的文件)或其他本地文件路径或清单文件的完整HTTP URI。唯一标识符可以用于
external角色，以便清楚目标属于哪个interphinx集合。 一个像这样的链接:external+python:ref:`comparison manual <comparisons>`将链接到文档集“python”中的标签“comparisons”（如果存在）。Example
要在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文档时，更新清单文件由您决定。Multiple targets for the inventory
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)), }
- intersphinx_resolve_self¶
- 类型:
str- 默认:
''
如果提供，
intersphinx_resolve_self重写interphinx的解析机制以解析对当前项目的所有引用，而不是外部引用。当文档在项目之间共享时，这很有用，“上游”或“父”项目在其文档中使用interphinx风格的引用。例如，诸如此类的项目 Astropy 可以设置：intersphinx_resolve_self = 'astropy'
项目重复利用 Astropy 的文档或继承它们的文档字符串，
intersphinx_mapping与'astropy'键，指向 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 秒
- intersphinx_disabled_reftypes¶
- 类型:
Sequence[str]- 默认:
['std:doc']
Added in version 4.3.
在 5.0 版本发生变更: 将缺省值从空列表更改为
['std:doc']。字符串列表为以下任一项：
域中特定引用类型的名称，例如，
std:doc，py:func，或cpp:class，域名和通配符，例如，
std:*，py:*，或cpp:*，或简单的通配符
*。
当一个非 -
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'，例如，:external:doc:`installation.用这个简写，假设该域是 ``std` .
如果要将查找限制到特定的外部项目，则该项目的键，如
intersphinx_mapping也被添加，以获得这两个表单
显示Intersphinx映射文件的所有链接¶
要显示Interphinx映射文件的所有Interphinx链接及其目标，请运行 python -m sphinx.ext.intersphinx url-or-path . 在文档项目中搜索Intersphinx链接断开的根本原因时，这很有帮助。下面的示例打印Python文档的Intersphinx映射：
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv