mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
71 lines
2.9 KiB
ReStructuredText
71 lines
2.9 KiB
ReStructuredText
:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
|
|
======================================================================
|
|
|
|
.. module:: sphinx.ext.intersphinx
|
|
:synopsis: Link to other Sphinx documentation.
|
|
|
|
.. index:: pair: automatic; linking
|
|
|
|
.. versionadded:: 0.5
|
|
|
|
This extension can generate automatic links to the documentation of Python
|
|
objects in other projects. This works as follows:
|
|
|
|
* Each Sphinx HTML build creates a file named :file:`objects.inv` that
|
|
contains a mapping from Python identifiers to URIs relative to the HTML set's
|
|
root.
|
|
|
|
* Projects using the Intersphinx extension can specify the location of such
|
|
mapping files in the :confval:`intersphinx_mapping` config value. The mapping
|
|
will then be used to resolve otherwise missing references to Python objects
|
|
into links to the other documentation.
|
|
|
|
* By default, the mapping file is assumed to be at the same location as the rest
|
|
of the documentation; however, the location of the mapping file can also be
|
|
specified individually, e.g. if the docs should be buildable without Internet
|
|
access.
|
|
|
|
To use intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your
|
|
:confval:`extensions` config value, and use these new config values to activate
|
|
linking:
|
|
|
|
.. confval:: intersphinx_mapping
|
|
|
|
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.
|
|
|
|
Relative local paths in the keys are taken as relative to the base of the
|
|
built documentation, while relative local paths in the values are taken as
|
|
relative to the source directory.
|
|
|
|
An example, to add links to modules and objects in the Python standard
|
|
library documentation::
|
|
|
|
intersphinx_mapping = {'http://docs.python.org/dev': None}
|
|
|
|
This will download the corresponding :file:`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 redownloaded
|
|
whenever you do a full rebuild.
|
|
|
|
A second example, showing the meaning of a non-``None`` value::
|
|
|
|
intersphinx_mapping = {'http://docs.python.org/dev': 'python-inv.txt'}
|
|
|
|
This will read the inventory from :file:`python.inv` in the source
|
|
directory, but still generate links to the pages under
|
|
``http://docs.python.org/dev``. It is up to you to update the inventory file
|
|
as new objects are added to the Python documentation.
|
|
|
|
When fetching remote inventory files, proxy settings will be read from
|
|
the ``$HTTP_PROXY`` environment variable.
|
|
|
|
.. confval:: 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.
|