1:mod:`sphinx.ext.intersphinx` -- Link to other projects' documentation
2======================================================================
3
4.. module:: sphinx.ext.intersphinx
5   :synopsis: Link to other Sphinx documentation.
6
7.. index:: pair: automatic; linking
8
9.. versionadded:: 0.5
10
11This extension can generate automatic links to the documentation of objects in
12other projects.
13
14Usage is simple: whenever Sphinx encounters a cross-reference that has no
15matching target in the current documentation set, it looks for targets in the
16documentation sets configured in :confval:`intersphinx_mapping`.  A reference
17like ``:py:class:`zipfile.ZipFile``` can then link to the Python documentation
18for the ZipFile class, without you having to specify where it is located
19exactly.
20
21When using the "new" format (see below), you can even force lookup in a foreign
22set by prefixing the link target appropriately.  A link like ``:ref:`comparison
23manual <python:comparisons>``` will then link to the label "comparisons" in the
24doc set "python", if it exists.
25
26Behind the scenes, this works as follows:
27
28* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains
29  a mapping from object names to URIs relative to the HTML set's root.
30
31* Projects using the Intersphinx extension can specify the location of such
32  mapping files in the :confval:`intersphinx_mapping` config value.  The mapping
33  will then be used to resolve otherwise missing references to objects into
34  links to the other documentation.
35
36* By default, the mapping file is assumed to be at the same location as the rest
37  of the documentation; however, the location of the mapping file can also be
38  specified individually, e.g. if the docs should be buildable without Internet
39  access.
40
41
42Configuration
43-------------
44
45To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your
46:confval:`extensions` config value, and use these config values to activate
47linking:
48
49.. confval:: intersphinx_mapping
50
51   This config value contains the locations and names of other projects that
52   should be linked to in this documentation.
53
54   Relative local paths for target locations are taken as relative to the base
55   of the built documentation, while relative local paths for inventory
56   locations are taken as relative to the source directory.
57
58   When fetching remote inventory files, proxy settings will be read from
59   the ``$HTTP_PROXY`` environment variable.
60
61   **Old format for this config value**
62
63   This is the format used before Sphinx 1.0.  It is still recognized.
64
65   A dictionary mapping URIs to either ``None`` or an URI.  The keys are the
66   base URI of the foreign Sphinx documentation sets and can be local paths or
67   HTTP URIs.  The values indicate where the inventory file can be found: they
68   can be ``None`` (at the same location as the base URI) or another local or
69   HTTP URI.
70
71   **New format for this config value**
72
73   .. versionadded:: 1.0
74
75   A dictionary mapping unique identifiers to a tuple ``(target, inventory)``.
76   Each ``target`` is the base URI of a foreign Sphinx documentation set and can
77   be a local path or an HTTP URI.  The ``inventory`` indicates where the
78   inventory file can be found: it can be ``None`` (an :file:`objects.inv` file
79   at the same location as the base URI) or another local file path or a full
80   HTTP URI to an inventory file.
81
82   The unique identifier can be used to prefix cross-reference targets, so that
83   it is clear which intersphinx set the target belongs to.  A link like
84   ``:ref:`comparison manual <python:comparisons>``` will link to the label
85   "comparisons" in the doc set "python", if it exists.
86
87   **Example**
88
89   To add links to modules and objects in the Python standard library
90   documentation, use::
91
92      intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
93
94   This will download the corresponding :file:`objects.inv` file from the
95   Internet and generate links to the pages under the given URI.  The downloaded
96   inventory is cached in the Sphinx environment, so it must be re-downloaded
97   whenever you do a full rebuild.
98
99   A second example, showing the meaning of a non-``None`` value of the second
100   tuple item::
101
102      intersphinx_mapping = {'python': ('https://docs.python.org/3',
103                                        'python-inv.txt')}
104
105   This will read the inventory from :file:`python-inv.txt` in the source
106   directory, but still generate links to the pages under
107   ``https://docs.python.org/3``.  It is up to you to update the inventory file
108   as new objects are added to the Python documentation.
109
110   **Multiple targets for the inventory**
111
112   .. versionadded:: 1.3
113
114   Alternative files can be specified for each inventory. One can give a
115   tuple for the second inventory tuple item as shown in the following
116   example. This will read the inventory iterating through the (second)
117   tuple items until the first successful fetch. The primary use case for
118   this to specify mirror sites for server downtime of the primary
119   inventory::
120
121      intersphinx_mapping = {'python': ('https://docs.python.org/3',
122                                        (None, 'python-inv.txt'))}
123
124   For a set of books edited and tested locally and then published
125   together, it could be helpful to try a local inventory file first,
126   to check references before publication::
127
128      intersphinx_mapping = {
129          'otherbook':
130              ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
131                  ('../../otherbook/build/html/objects.inv', None)),
132      }
133
134.. confval:: intersphinx_cache_limit
135
136   The maximum number of days to cache remote inventories.  The default is
137   ``5``, meaning five days.  Set this to a negative value to cache inventories
138   for unlimited time.
139
140.. confval:: intersphinx_timeout
141
142   The number of seconds for timeout.  The default is ``None``, meaning do not
143   timeout.
144
145   .. note::
146
147      timeout is not a time limit on the entire response download; rather, an
148      exception is raised if the server has not issued a response for timeout
149      seconds.
150
151
152Showing all links of an Intersphinx mapping file
153------------------------------------------------
154
155To show all Intersphinx links and their targets of an Intersphinx mapping file,
156run ``python -msphinx.ext.intersphinx url-or-path``.  This is helpful when
157searching for the root cause of a broken Intersphinx link in a documentation
158project. The following example prints the Intersphinx mapping of the Python 3
159documentation::
160
161   $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
162
163Using Intersphinx with inventory file under Basic Authorization
164---------------------------------------------------------------
165
166Intersphinx supports Basic Authorization like this::
167
168      intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
169                                        None)}
170
171The user and password will be stripped from the URL when generating the links.
172