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

0.5 新版功能.

此扩展可以生成指向其他项目中对象文档的自动链接。

用法很简单:只要Sphinx遇到当前文档集中没有匹配目标的交叉引用，它就会在配置的文档集中查找目标 intersphinx_mapping 。然后像 :py:class:`zipfile.ZipFile` 这样的引用可以链接到ZipFile类的Python文档，而不必指定它所在的位置。

使用 “new” 格式（见下文）时，您甚至可以通过为链接目标添加适当的前缀来强制在外部集合中查找。 像 :ref:`comparison manual <python:comparisons>` 这样的链接将链接到 doc set “python” 中的标签 “comparisons” ，如果它存在的话。

在幕后，这工作如下:

  • 每个Sphinx HTML构建都会创建一个名为 objects.inv 的文件，其中包含从对象名称到相对于HTML集合根目录的URI的映射。

  • 使用Intersphinx扩展的项目可以在 intersphinx_mapping 配置值中指定此类映射文件的位置。然后，映射将用于解析对象的其他缺失引用，并将其转换为指向其他文档的链接。

  • 默认情况下，假定映射文件与文档的其余部分位于同一位置;但是，映射文件的位置也可以单独指定，例如，如果文档应该可以在没有Internet访问的情况下构建。

配置

To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your extensions config value, and use these config values to activate linking:

intersphinx_mapping

This config value contains the locations and names of other projects that should be linked to in this documentation.

Relative local paths for target locations are taken as relative to the base of the built documentation, while relative local paths for inventory locations are taken as relative to the source directory.

When fetching remote inventory files, proxy settings will be read from the $HTTP_PROXY environment variable.

Old format for this config value

This is the format used before Sphinx 1.0. It is still recognized.

A dictionary mapping URIs to either None or an URI. The keys are the base URI of the foreign Sphinx documentation sets and can be local paths or HTTP URIs. The values indicate where the inventory file can be found: they can be None (at the same location as the base URI) or another local or HTTP URI.

New format for this config value

1.0 新版功能.

A dictionary mapping unique identifiers to a tuple (target, inventory). Each target is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. The inventory indicates where the inventory file can be found: it can be None (at the same location as the base URI) or another local or HTTP URI.

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

Example

To add links to modules and objects in the Python standard library documentation, use:

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

This will download the corresponding objects.inv file from the Internet and generate links to the pages under the given URI. The downloaded inventory is cached in the Sphinx environment, so it must be re-downloaded whenever you do a full rebuild.

A second example, showing the meaning of a non-None value of the second tuple item:

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

This will read the inventory from python-inv.txt in the source directory, but still generate links to the pages under https://docs.python.org/3. It is up to you to update the inventory file as new objects are added to the Python documentation.

Multiple target for the inventory

1.3 新版功能.

Alternative files can be specified for each inventory. One can give a tuple for the second inventory tuple item as shown in the following example. This will read the inventory iterating through the (second) tuple items until the first successful fetch. The primary use case for this to specify mirror sites for server downtime of the primary inventory:

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

The maximum number of days to cache remote inventories. The default is 5, meaning five days. Set this to a negative value to cache inventories for unlimited time.

intersphinx_timeout

The number of seconds for timeout. The default is None, meaning do not timeout.

注解

timeout is not a time limit on the entire response download; rather, an exception is raised if the server has not issued a response for timeout seconds.