mod:sphinx.ext.ext.intersphinx – Lien vers la documentation d’autres projets¶
Added in version 0.5.
This extension can generate links to the documentation of objects in external
projects, either explicitly through the external
role, or as a
fallback resolution for any other cross-reference.
Usage for fallback resolution is simple: whenever Sphinx encounters a
cross-reference that has no matching target in the current documentation set,
it looks for targets in the external documentation sets configured in
intersphinx_mapping
. A reference like
:py:class:`zipfile.ZipFile`
can then link to the Python documentation
for the ZipFile class, without you having to specify where it is located
exactly.
When using the external
role, you can force lookup to any external
projects, and optionally to a specific external project.
A link like :external:ref:`comparison manual <comparisons>`
will then link
to the label « comparisons » in whichever configured external project, if it
exists,
and a link like :external+python:ref:`comparison manual <comparisons>`
will
link to the label « comparisons » only in the doc set « python », if it exists.
Dans les coulisses, cela fonctionne comme suit :
Chaque compilation HTML de Sphinx crée un fichier nommé
objects.inv
qui contient un mappage des noms d’objets aux URIs par rapport à la racine de l’ensemble HTML.Projects using the Intersphinx extension can specify the location of such mapping files in the
intersphinx_mapping
config value. The mapping will then be used to resolve bothexternal
references, and also otherwise missing references to objects into links to the other documentation.Par défaut, le fichier cartographique est supposé se trouver au même emplacement que le reste de la documentation ; cependant, l’emplacement du fichier cartographique peut également être spécifié individuellement, par exemple si les documents doivent pouvoir être construits sans accès Internet.
Configuration¶
To use Intersphinx linking, add 'sphinx.ext.intersphinx'
to your
extensions
config value, and use these config values to activate
linking:
- intersphinx_mapping¶
Cette valeur de configuration contient les emplacements et les noms des autres projets qui doivent être liés dans cette documentation.
Les chemins locaux relatifs pour les emplacements cibles sont considérés comme relatifs par rapport à la base de la documentation construite, tandis que les chemins locaux relatifs pour les emplacements d’inventaire sont considérés comme relatifs par rapport au répertoire source.
Lors de la récupération de fichiers d’inventaire distants, les paramètres proxy seront lus à partir de la variable d’environnement
$HTTP_PROXY
.Format
Added in version 1.0.
A dictionary mapping unique identifiers to a tuple
(target, inventory)
. Eachtarget
is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. Theinventory
indicates where the inventory file can be found: it can beNone
(anobjects.inv
file at the same location as the base URI) or another local file path or a full HTTP URI to an inventory file.The unique identifier can be used in the
external
role, so that it is clear which intersphinx set the target belongs to. A link likeexternal:python+ref:`comparison manual <comparisons>`
will link to the label « comparisons » in the doc set « python », if it exists.Exemple
Pour ajouter des liens vers des modules et des objets dans la documentation de la bibliothèque standard Python, utilisez:
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
Cela téléchargera le fichier
objects.inv
correspondant depuis Internet et générera des liens vers les pages sous l’URI donnée. L’inventaire téléchargé est mis en cache dans l’environnement Sphinx, il doit donc être téléchargé à nouveau chaque fois que vous faites une reconstruction complète.Un deuxième exemple, montrant la signification d’une valeur non-
None`
du deuxième élément tuple: :intersphinx_mapping = {'python': ('https://docs.python.org/3', 'python-inv.txt')}
Ceci lira l’inventaire à partir du fichier
python-inv.txt
dans le répertoire source, mais générera toujours des liens vers les pages soushttps://docs.python.org/3`
. C’est à vous de mettre à jour le fichier d’inventaire au fur et à mesure que de nouveaux objets sont ajoutés à la documentation Python.Multiple targets for the inventory
Added in version 1.3.
Des fichiers alternatifs peuvent être spécifiés pour chaque inventaire. On peut donner un tuple pour le deuxième élément du tuple d’inventaire comme le montre l’exemple suivant. Ceci lira l’itération de l’inventaire à travers le (second) tuple des items jusqu’à ce que le premier chargement soit réussi. Le cas d’utilisation principal pour ceci pour spécifier les sites miroirs pour les temps d’arrêt du serveur de l’inventaire primaire: :
intersphinx_mapping = {'python': ('https://docs.python.org/3', (None, 'python-inv.txt'))}
For a set of books edited and tested locally and then published together, it could be helpful to try a local inventory file first, to check references before publication:
intersphinx_mapping = { 'otherbook': ('https://myproj.readthedocs.io/projects/otherbook/en/latest', ('../../otherbook/build/html/objects.inv', None)), }
**Ancien format pour cette valeur de configuration *
Obsolète depuis la version 6.2.
Prudence
This is the format used before Sphinx 1.0. It is deprecated and will be removed in Sphinx 8.0.
Un dictionnaire mappant les URIs soit à
Aucun
soit à un URI. Les clés sont l’URI de base des jeux de documentation Sphinx étrangers et peuvent être des chemins locaux ou des URI HTTP. Les valeurs indiquent où se trouve le fichier d’inventaire : elles peuvent êtreAucune
(au même endroit que l’URI de base) ou une autre URI locale ou HTTP.Exemple:
intersphinx_mapping = {'https://docs.python.org/': None}
- intersphinx_cache_limit¶
Le nombre maximum de jours pour mettre en cache les inventaires distants. La valeur par défaut est « 5 », c’est-à-dire cinq jours. Définissez cette valeur à une valeur négative pour mettre en cache les inventaires pour une durée illimitée.
- intersphinx_timeout¶
Le nombre de secondes pour le délai d’attente. La valeur par défaut est ``None””, ce qui signifie qu’il n’y a pas de délai d’attente.
Note
timeout n’est pas une limite de temps sur l’ensemble du téléchargement de la réponse ; plutôt, une exception est levée si le serveur n’a pas émis une réponse pendant les secondes de timeout.
- intersphinx_disabled_reftypes¶
Added in version 4.3.
Modifié dans la version 5.0: Changed default value from an empty list to
['std:doc']
.A list of strings being either:
the name of a specific reference type in a domain, e.g.,
std:doc
,py:func
, orcpp:class
,the name of a domain, and a wildcard, e.g.,
std:*
,py:*
, orcpp:*
, orsimply a wildcard
*
.
The default value is
['std:doc']
.When a non-
external
cross-reference is being resolved by intersphinx, skip resolution if it matches one of the specifications in this list.For example, with
intersphinx_disabled_reftypes = ['std:doc']
a cross-reference:doc:`installation`
will not be attempted to be resolved by intersphinx, but:external+otherbook:doc:`installation`
will be attempted to be resolved in the inventory namedotherbook
inintersphinx_mapping
. At the same time, all cross-references generated in, e.g., Python, declarations will still be attempted to be resolved by intersphinx.If
*
is in the list of domains, then no non-external
references will be resolved by intersphinx.
Explicitly Reference External Objects¶
The Intersphinx extension provides the following role.
- :external:¶
Added in version 4.4.
Use Intersphinx to perform lookup only in external projects, and not the current project. Intersphinx still needs to know the type of object you would like to find, so the general form of this role is to write the cross-refererence as if the object is in the current project, but then prefix it with
:external
. The two forms are then:external:domain:reftype:`target`
, e.g.,:external:py:class:`zipfile.ZipFile`
, or:external:reftype:`target`
, e.g.,:external:doc:`installation`
. With this shorthand, the domain is assumed to bestd
.
If you would like to constrain the lookup to a specific external project, then the key of the project, as specified in
intersphinx_mapping
, is added as well to get the two forms:external+invname:domain:reftype:`target`
, e.g.,:external+python:py:class:`zipfile.ZipFile`
, or:external+invname:reftype:`target`
, e.g.,:external+python:doc:`installation`
.
Afficher tous les liens d’un fichier de mappage Intersphinx¶
Pour afficher tous les liens Intersphinx et leurs cibles d’un fichier de mappage Intersphinx, exécutez python -msphinx.ext.intersphinx url-or-path
. Ceci est utile lors de la recherche de la cause fondamentale d’un lien Intersphinx rompu dans un projet de documentation. L’exemple suivant imprime le mapping Intersphinx de la documentation Python 3: :
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv