Intersphinx

sphinx.ext.intersphinx ermöglicht die Verknüpfung mit anderen Projektdokumentationen.

Konfiguration

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

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

Externe Sphinx-Dokumentation kann dann angegeben werden, z.B. mit:

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

Es können jedoch auch alternative Dateien für eine Bestandsaufnahme angegeben werden, z.B.:

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

Bestimmen von Linkzielen

Um die in einem Inventar verfügbaren 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 ist, z.B.:

WARNING: Unknown interpreted text role "confval".

so könnt ihr sie 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",
    )