Linking to other projects¶
With sphinx.ext.intersphinx, references this project cannot resolve are looked up
in other projects’ inventories, the objects.inv every Sphinx or Guidedog site
publishes. Name the projects in conf.toml:
extensions = ["sphinx.ext.intersphinx"]
[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]
Each entry is the address of the other project’s pages and where its inventory is: a
URL, a file relative to the source folder, or "" for the objects.inv at the
address. A list is tried in order. This is Sphinx’s intersphinx_mapping, with ""
for Python’s None; guidedog migrate converts it.
Then references need nothing new:
:func:`len`, :class:`list`, and :ref:`tut-packages` link into Python's documentation.
:ref:`click:testing` looks only in Click's inventory.
:external+python:ref:`tut-packages` never looks in this project.
Links show the other project’s titles for labels and documents, and carry a tooltip
such as “(in Python v3.14)”. As in Sphinx, :doc: references need the project’s
name (:doc:`python:tutorial/index`), because intersphinx_disabled_reftypes is
["std:doc"] by default.
Inventories are fetched when a build starts and kept in
_build/.doctrees/__intersphinx_cache__ for intersphinx_cache_limit days (5; a
negative number keeps them); local files are read on every build. As in Sphinx, an
inventory that has moved (its URL redirects, as
https://werkzeug.palletsprojects.com/objects.inv redirects to /en/stable/) makes
its new folder the base of the links, and the cache remembers that base, so a build
from the cache links exactly as the build that fetched it did.
intersphinx_timeout limits each download in seconds. A project that cannot be
reached is a warning, and its references stay unresolved.
Guidedog writes its own objects.inv with every page, label, term, and object, so
other projects can link here the same way.