diff options
Diffstat (limited to 'doc/ext/intersphinx.rst')
| -rw-r--r-- | doc/ext/intersphinx.rst | 65 |
1 files changed, 45 insertions, 20 deletions
diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index 6a079cd48..29b4057f1 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -8,17 +8,16 @@ .. versionadded:: 0.5 -This extension can generate automatic links to the documentation of Python -objects in other projects. This works as follows: +This extension can generate automatic links to the documentation of 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. +* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains + a mapping from object names 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. + will then be used to resolve otherwise missing references to 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 @@ -31,37 +30,63 @@ linking: .. confval:: 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. - 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. + **New format for this config value** - An example, to add links to modules and objects in the Python standard - library documentation:: + .. versionadded:: 1.0 - intersphinx_mapping = {'http://docs.python.org/': None} + 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': ('http://docs.python.org/', 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:: + A second example, showing the meaning of a non-``None`` value of the second + tuple item:: - intersphinx_mapping = {'http://docs.python.org/': 'python-inv.txt'} + intersphinx_mapping = {'python': ('http://docs.python.org/', + 'python-inv.txt')} This will read the inventory from :file:`python-inv.txt` in the source directory, but still generate links to the pages under - ``http://docs.python.org/``. 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. + ``http://docs.python.org/``. It is up to you to update the inventory file as + new objects are added to the Python documentation. .. confval:: intersphinx_cache_limit |