Enlazar con otros proyectos¶
Con sphinx.ext.intersphinx, las referencias no resueltas se buscan en los inventarios de otros proyectos: el objects.inv que publica cada sitio Sphinx o Guidedog. Indique los proyectos en conf.toml:
extensions = ["sphinx.ext.intersphinx"]
[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]
Cada entrada contiene la dirección de las páginas y la ubicación del inventario: URL, archivo relativo al directorio de fuentes o "" para el objects.inv de esa dirección. Las listas se prueban por orden. Es el intersphinx_mapping de Sphinx con "" en lugar de None de Python; guidedog migrate lo convierte.
Las referencias no necesitan nada más:
: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.
Los enlaces usan los títulos del otro proyecto para etiquetas y documentos y un texto emergente como «(in Python v3.14)». Como en Sphinx, :doc: necesita el nombre del proyecto (:doc:`python:tutorial/index`), porque intersphinx_disabled_reftypes es ["std:doc"] por defecto.
Los inventarios se descargan al comenzar y se guardan en _build/.doctrees/__intersphinx_cache__ durante intersphinx_cache_limit días: 5 por defecto; un valor negativo los conserva. Los archivos locales se leen en cada build. Como en Sphinx, una redirección cambia la base de los enlaces y la caché la recuerda, manteniendo los mismos enlaces. Por ejemplo, https://werkzeug.palletsprojects.com/objects.inv redirige a /en/stable/. intersphinx_timeout limita cada descarga en segundos. Si un proyecto no es accesible, se advierte y sus referencias quedan sin resolver.
Guidedog escribe su propio objects.inv con páginas, etiquetas, términos y objetos, para que otros proyectos puedan enlazar aquí del mismo modo.