：模式：sphinx.ext.intersphinx–链接到其他文档

Added in version 0.5.

This extension can generate links to the documentation of objects in external projects, either explicitly through the external role, or as a fallback resolution for any other cross-reference.

Usage for fallback resolution is simple: whenever Sphinx encounters a cross-reference that has no matching target in the current documentation set, it looks for targets in the external documentation sets configured in intersphinx_mapping. A reference like :py:class:`zipfile.ZipFile` can then link to the Python documentation for the ZipFile class, without you having to specify where it is located exactly.

When using the external role, you can force lookup to any external projects, and optionally to a specific external project. A link like :external:ref:`comparison manual <comparisons>` will then link to the label “comparisons” in whichever configured external project, if it exists, and a link like :external+python:ref:`comparison manual <comparisons>` will link to the label “comparisons” only in the doc set “python”, if it exists.

在幕后，它的工作原理如下：

  • 每个Sphinx HTML构建都会创建一个名为：file:`objects.inv`包含从对象名到相对于HTML集根的uri的映射。

  • Projects using the Intersphinx extension can specify the location of such mapping files in the intersphinx_mapping config value. The mapping will then be used to resolve both external references, and also otherwise missing references to objects into links to the other documentation.

  • 默认情况下，假定映射文件与其余文档位于同一位置；但是，也可以单独指定映射文件的位置，例如，如果文档应该可以在不访问Internet的情况下生成。

配置

要使用Intersphinx链接，请添加“`”sphinx.ext.intersphinx景“``到您的：confval:`extensions”配置值，并使用这些配置值激活链接：

intersphinx_mapping

此配置值包含应在此文档中链接到的其他项目的位置和名称。

目标位置的相对本地路径被视为相对于构建文档的基础，而库存位置的相对本地路径被视为相对于源目录。

获取远程清单文件时，将从`$HTTP_proxy``环境变量中读取代理设置。

Format

Added in version 1.0.

将唯一标识符映射到元组 (target, inventory) 的字典。每个 target 都是外部Sphinx文档集的基URI，可以是本地路径或httpuri。 inventory 指示可以在何处找到清单文件：它可以是“None”（一个 objects.inv 文件与URI位于同一位置）或另一个本地路径或完整的HTTP URI指向清单文件。

The unique identifier can be used in the external role, so that it is clear which intersphinx set the target belongs to. A link like external:python+ref:`comparison manual <comparisons>` will link to the label “comparisons” in the doc set “python”, if it exists.

举例

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

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

这将下载相应的：文件：`对象.inv`从Internet上创建文件并生成指向给定URI下的页面的链接。下载的资源清册缓存在Sphinx环境中，因此在进行完全重建时必须重新下载。

第二个示例显示了第二个元组项的非“None”值的含义：

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

这将从以下位置读取清单：file:python-inv.txt`在源目录中，但仍生成指向下页的链接``https://docs.python.org/3`. 当新对象添加到Python文档中时，由您来更新库存文件。

库存的多个目标

Added in version 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)),
}

Old format for this config value

自 6.2 版本弃用.

小心

This is the format used before Sphinx 1.0. It is deprecated and will be removed in Sphinx 8.0.

将URI映射到“None”或URI的字典。键是外部Sphinx文档集的基本URI，可以是本地路径或httpuri。这些值指示可以在何处找到清单文件：它们可以是“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 版本发生变更: Changed default value from an empty list to ['std:doc'].

A list of strings being either:

  • the name of a specific reference type in a domain, e.g., std:doc, py:func, or cpp:class,

  • the name of a domain, and a wildcard, e.g., std:*, py:*, or cpp:*, or

  • simply a wildcard *.

The default value is ['std:doc'].

When a non-external cross-reference is being resolved by intersphinx, skip resolution if it matches one of the specifications in this list.

For example, with intersphinx_disabled_reftypes = ['std:doc'] a cross-reference :doc:`installation` will not be attempted to be resolved by intersphinx, but :external+otherbook:doc:`installation` will be attempted to be resolved in the inventory named otherbook in intersphinx_mapping. At the same time, all cross-references generated in, e.g., Python, declarations will still be attempted to be resolved by intersphinx.

If * is in the list of domains, then no non-external references will be resolved by intersphinx.

Explicitly Reference External Objects

The Intersphinx extension provides the following role.

:external:

Added in version 4.4.

Use Intersphinx to perform lookup only in external projects, and not the current project. Intersphinx still needs to know the type of object you would like to find, so the general form of this role is to write the cross-refererence as if the object is in the current project, but then prefix it with :external. The two forms are then

  • :external:domain:reftype:`target`, e.g., :external:py:class:`zipfile.ZipFile`, or

  • :external:reftype:`target`, e.g., :external:doc:`installation`. With this shorthand, the domain is assumed to be std.

If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in intersphinx_mapping, is added as well to get the two forms

  • :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和库存文件

Intersphinx支持如下基本授权：

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

生成链接时，用户和密码将从URL中删除。