sphinx.ext.intersphinx -- 链接到其他项目的文档

Added in version 0.5.

此插件可以生成到外部项目中对象文档的链接，可以通过 external 角色显式地生成，也可以作为任何其他交叉引用的后备解析。

后备解析的用法很简单：每当 Sphinx 遇到当前文档集中没有匹配目标的交叉引用时，它会查找在 intersphinx_mapping 中配置的外部文档集中的目标。例如，:py:class:`zipfile.ZipFile` 可以链接到 Python 文档中 ZipFile 类的文档，而无需您指定其确切位置。

使用 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 环境变量中读取。

格式

Added in version 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.python.org/3', None)}

这将从互联网下载相应的 objects.inv 文件，并生成链接到给定 URI 下的页面。

第二个示例，显示第二个元组项的非 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)),
}
intersphinx_cache_limit

缓存远程清单的最大天数。默认值为 5，表示五天。将其设置为负值以无限期缓存清单。

intersphinx_timeout

超时的秒数。默认值为 None，表示不超时。

Note

超时不是整个响应下载的时间限制；而是如果服务器在超时秒内没有发出响应，则会引发异常。

intersphinx_disabled_reftypes

Added in version 4.3.

Changed in version 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` 将尝试在 intersphinx_mapping 中命名为 otherbook 的清单中解析。同时，例如 Python 中生成的所有交叉引用声明仍将尝试通过 intersphinx 解析。

如果 * 在域列表中，则不会通过 intersphinx 解析非 external 引用。

显式引用外部对象

Intersphinx 插件提供了以下角色。

:external:

Added in version 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_mapping = {'python': ('https://user:password@docs.python.org/3',
                                  None)}

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