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