Intersphinx

sphinx.ext.intersphinx erlaubt die Verlinkung von anderen Projekt-Dokumentationen.

Konfiguration

In source/conf.py muss Intersphinx als Erweiterung angegeben werden:

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

Anschließend können externe Sphinx-Dokumentationen angegeben werden, z.B. mit:

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

Für ein Inventar können jedoch auch alternative Dateien angegeben werden, z.B.:

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

Linkziele ermitteln

Um die in einem Inventar zur Verfügung stehenden Links zu ermitteln, könnt ihr z.B. folgendes eingeben:

$ 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

Rollen hinzufügen

Wenn ihr eine Fehlermeldung erhaltet, dass eine bestimmte Textrolle unbekannt sei, z.B.

WARNING: Unknown interpreted text role "confval".

so könnt ihr diese in der conf.py hinzufügen:

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",
    )