intersphinx role, documentation

This commit is contained in:
Jakob Lykke Andersen 2021-11-06 15:27:31 +01:00
parent ccc4f95b42
commit 540d76035c

View File

@ -8,20 +8,25 @@
.. versionadded:: 0.5 .. versionadded:: 0.5
This extension can generate automatic links to the documentation of objects in This extension can generate links to the documentation of objects in external
other projects. projects, either explicitly through the :rst:role:`external` role, or as a
fallback resolution for any other cross-reference.
Usage is simple: whenever Sphinx encounters a cross-reference that has no Usage for fallback resolution is simple: whenever Sphinx encounters a
matching target in the current documentation set, it looks for targets in the cross-reference that has no matching target in the current documentation set,
documentation sets configured in :confval:`intersphinx_mapping`. A reference it looks for targets in the external documentation sets configured in
like ``:py:class:`zipfile.ZipFile``` can then link to the Python documentation :confval:`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 for the ZipFile class, without you having to specify where it is located
exactly. exactly.
When using the "new" format (see below), you can even force lookup in a foreign When using the :rst:role:`external` role, you can force lookup to any external
set by prefixing the link target appropriately. A link like ``:ref:`comparison projects, and optionally to a specific external project.
manual <python:comparisons>``` will then link to the label "comparisons" in the A link like ``:external:ref:`comparison manual <comparisons>``` will then link
doc set "python", if it exists. 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.
Behind the scenes, this works as follows: Behind the scenes, this works as follows:
@ -30,8 +35,8 @@ Behind the scenes, this works as follows:
* Projects using the Intersphinx extension can specify the location of such * Projects using the Intersphinx extension can specify the location of such
mapping files in the :confval:`intersphinx_mapping` config value. The mapping mapping files in the :confval:`intersphinx_mapping` config value. The mapping
will then be used to resolve otherwise missing references to objects into will then be used to resolve both :rst:role:`external` references, and also
links to the other documentation. otherwise missing references to objects into links to the other documentation.
* By default, the mapping file is assumed to be at the same location as the rest * By default, the mapping file is assumed to be at the same location as the rest
of the documentation; however, the location of the mapping file can also be of the documentation; however, the location of the mapping file can also be
@ -79,10 +84,10 @@ linking:
at the same location as the base URI) or another local file path or a full at the same location as the base URI) or another local file path or a full
HTTP URI to an inventory file. HTTP URI to an inventory file.
The unique identifier can be used to prefix cross-reference targets, so that The unique identifier can be used in the :rst:role:`external` role, so that
it is clear which intersphinx set the target belongs to. A link like it is clear which intersphinx set the target belongs to. A link like
``:ref:`comparison manual <python:comparisons>``` will link to the label ``external:python+ref:`comparison manual <comparisons>``` will link to the
"comparisons" in the doc set "python", if it exists. label "comparisons" in the doc set "python", if it exists.
**Example** **Example**
@ -162,21 +167,50 @@ linking:
The default value is an empty list. The default value is an empty list.
When a cross-reference without an explicit inventory specification is being When a non-:rst:role:`external` cross-reference is being resolved by
resolved by intersphinx, skip resolution if it matches one of the intersphinx, skip resolution if it matches one of the specifications in this
specifications in this list. list.
For example, with ``intersphinx_disabled_reftypes = ['std:doc']`` For example, with ``intersphinx_disabled_reftypes = ['std:doc']``
a cross-reference ``:doc:`installation``` will not be attempted to be a cross-reference ``:doc:`installation``` will not be attempted to be
resolved by intersphinx, but ``:doc:`otherbook:installation``` will be resolved by intersphinx, but ``:external:otherbook+doc:`installation``` will
attempted to be resolved in the inventory named ``otherbook`` in be attempted to be resolved in the inventory named ``otherbook`` in
:confval:`intersphinx_mapping`. :confval:`intersphinx_mapping`.
At the same time, all cross-references generated in, e.g., Python, At the same time, all cross-references generated in, e.g., Python,
declarations will still be attempted to be resolved by intersphinx. declarations will still be attempted to be resolved by intersphinx.
If ``*`` is in the list of domains, then no references without an explicit If ``*`` is in the list of domains, then no non-:rst:role:`external`
inventory will be resolved by intersphinx. references will be resolved by intersphinx.
Explicitly Reference External Objects
-------------------------------------
The Intersphinx extension provides the following role.
.. rst:role:: external
.. versionadded:: 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```.
If you would like to constrain the lookup to a specific external project,
then the key of the project, as specified in :confval:`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```.
Showing all links of an Intersphinx mapping file Showing all links of an Intersphinx mapping file
------------------------------------------------ ------------------------------------------------