Skip to content

Commit

Permalink
intersphinx role, documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
jakobandersen committed Jan 16, 2022
1 parent ccc4f95 commit 540d760
Showing 1 changed file with 57 additions and 23 deletions.
80 changes: 57 additions & 23 deletions doc/usage/extensions/intersphinx.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,25 @@

.. versionadded:: 0.5

This extension can generate automatic links to the documentation of objects in
other projects.

Usage is simple: whenever Sphinx encounters a cross-reference that has no
matching target in the current documentation set, it looks for targets in the
documentation sets configured in :confval:`intersphinx_mapping`. A reference
like ``:py:class:`zipfile.ZipFile``` can then link to the Python documentation
This extension can generate links to the documentation of objects in external
projects, either explicitly through the :rst:role:`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
: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
exactly.

When using the "new" format (see below), you can even force lookup in a foreign
set by prefixing the link target appropriately. A link like ``:ref:`comparison
manual <python:comparisons>``` will then link to the label "comparisons" in the
doc set "python", if it exists.
When using the :rst:role:`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.

Behind the scenes, this works as follows:

Expand All @@ -30,8 +35,8 @@ Behind the scenes, this works as follows:

* Projects using the Intersphinx extension can specify the location of such
mapping files in the :confval:`intersphinx_mapping` config value. The mapping
will then be used to resolve otherwise missing references to objects into
links to the other documentation.
will then be used to resolve both :rst:role:`external` references, and also
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
of the documentation; however, the location of the mapping file can also be
Expand Down Expand Up @@ -79,10 +84,10 @@ linking:
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 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
``:ref:`comparison manual <python:comparisons>``` will link to the label
"comparisons" in the doc set "python", if it exists.
``external:python+ref:`comparison manual <comparisons>``` will link to the
label "comparisons" in the doc set "python", if it exists.

**Example**

Expand Down Expand Up @@ -162,21 +167,50 @@ linking:

The default value is an empty list.

When a cross-reference without an explicit inventory specification is being
resolved by intersphinx, skip resolution if it matches one of the
specifications in this list.
When a non-:rst:role:`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 ``:doc:`otherbook:installation``` will be
attempted to be resolved in the inventory named ``otherbook`` in
resolved by intersphinx, but ``:external:otherbook+doc:`installation``` will
be attempted to be resolved in the inventory named ``otherbook`` in
:confval:`intersphinx_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 references without an explicit
inventory will be resolved by intersphinx.
If ``*`` is in the list of domains, then no non-:rst:role:`external`
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
------------------------------------------------
Expand Down

0 comments on commit 540d760

Please sign in to comment.