Intersphinx

sphinx.ext.intersphinx allows the linking of other project documentation.

Configuration

In docs/conf.py Intersphinx must be indicated as an extension:

extensions = [
    ...
    'sphinx.ext.intersphinx',
    ]

External Sphinx documentation can then be specified, e.g. with:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'bokeh':  ('https://bokeh.pydata.org/en/latest/', None)
}

However, alternative files can also be specified for an inventory, for example:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', (None, 'python-inv.txt'),
    ...
}

Determine link targets

To determine the links available in an inventory, you can enter the following, for example:

$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
c:function
    PyAnySet_Check                           c-api/set.html#c.PyAnySet_Check
    PyAnySet_CheckExact                      c-api/set.html#c.PyAnySet_CheckExact
    PyArg_Parse                              c-api/arg.html#c.PyArg_Parse
…

Create a link

In order to link to https://docs.python.org/3/c-api/arg.html#c.PyArg_Parse, one of the following variants can be specified:

PyArg_Parse()

:c:func:`PyArg_Parse`

PyArg_Parse()

:c:func:`!PyArg_Parse`

Parsing arguments

:c:func:`Parsing arguments <PyArg_Parse>`

Custom links

You can also create your own intersphinx assignments, e.g. if objects.inv in Beautiful Soup has errors.

The error can be corrected with:

1. Installation of sphobjinv:

   $ python -m pip install sphobjinv
   

2. Then the original file can be downloaded with:

   $ cd docs/build/
   $ mkdir _intersphinx
   $ !$
   $ curl -O https://www.crummy.com/software/BeautifulSoup/bs4/doc/objects.inv
   $ mv objects.inv bs4_objects.inv
   

3. Change the Sphinx configuration docs/conf.py:

   intersphinx_mapping = {
       …
       'bs4':    ('https://www.crummy.com/software/BeautifulSoup/bs4/doc/', "_intersphinx/bs4_objects.inv")
   }
   

4. Convert to a text file:

   $ sphobjinv convert plain bs4_objects.inv bs4_objects.txt
   

5. Editing the text file

   e.g.:

   bs4.BeautifulSoup           py:class  1 index.html#beautifulsoup -
   bs4.BeautifulSoup.get_text  py:method 1 index.html#get-text      -
   bs4.element.Tag             py:class  1 index.html#tag           -
   

   These entries can then be referenced in a Sphinx documentation with:

   - :class:`bs4.BeautifulSoup`
   - :meth:`bs4.BeautifulSoup.get_text`
   - :class:`bs4.element.Tag`
   

   See also

   • Sphinx objects.inv v2 Syntax

6. Create a new objects.inv file:

   $ sphobjinv convert zlib bs4_objects.txt bs4_objects.txt
   

7. Create Sphinx documentation:

   $ python -m sphinx -ab html docs/ docs/_build/
   

Add roles

If you get an error message that a certain text role is unknown, e.g.

WARNING: Unknown interpreted text role "confval".

so you can add them in the conf.py:

def setup(app):
    # from sphinx.ext.autodoc import cut_lines
    # app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
    app.add_object_type(
        "confval",
        "confval",
        objname="configuration value",
        indextemplate="pair: %s; configuration value",
    )