sphinx.ext.intersphinx – 链接到其他项目的文档¶
Added in version 0.5.
此扩展可以生成指向外部项目中对象文档的链接,既可以通过 external 角色显式生成,也可以作为其他交叉引用的后备解析.
备用解析的用法很简单:每当 Sphinx 遇到当前文档集中没有匹配目标的交叉引用时,它会在 intersphinx_mapping 配置的外部文档集中查找目标.像``:py:class:`zipfile.ZipFile```这样的引用可以链接到 ZipFile 类的 Python 文档,而无需您准确指定其位置.
在使用 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 下页面的链接.下载的清单缓存于 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)), }
- 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'].当通过 intersphinx 解析非
external交叉引用时,如果它与此列表中的某个规范匹配,则跳过解析.例如,使用
intersphinx_disabled_reftypes = ['std:doc']时,交叉引用``:doc:installation```将不会通过 intersphinx 尝试解析,但` 中名为otherbook的清单中进行解析.同时,所有在 Python 等中的声明生成的交叉引用仍将尝试通过 intersphinx 解析.如果
*在域列表中,则不返回任何非-external的引用通过intersphinx解析.
显式引用外部对象¶
Intersphinx扩展提供以下角色.
- :external:¶
Added in version 4.4.
使用 Intersphinx 仅在外部项目中进行查找,而不在当前项目中.Intersphinx 仍然需要知道您希望查找的对象类型,因此该角色的一般形式是将交叉引用写成仿佛对象在当前项目中,但随后以
:external为前缀.两种形式为:external:domain:reftype:`target`, 例如``:external:py:class:zipfile.ZipFile``, 或者, 例如``:external:doc:installation ` .使用这种简写,默认假定域为`` std`` .
如果您想将查找限制在特定的外部项目,则在
intersphinx_mapping中指定的项目键也会被添加,以获取这两种形式,例如,``
zipfile.ZipFile`,或:external+invname:reftype:`目标`, 例如,``:external+python:doc:安装` .
显示Intersphinx映射文件的所有链接¶
要显示 Intersphinx 映射文件的所有 Intersphinx 链接及其目标,请运行 python -msphinx.ext.intersphinx url-or-path .这在查找文档项目中断的 Intersphinx 链接的根本原因时非常有帮助.以下示例打印 Python 3 文档的 Intersphinx 映射:
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv