mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
intersphinx role, documentation
This commit is contained in:
parent
ccc4f95b42
commit
540d76035c
@ -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
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
Loading…
Reference in New Issue
Block a user