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
…

Einen Link erstellen

Um einen Link auf https://docs.python.org/3/c-api/arg.html#c.PyArg_Parse zu erstellen, kann eine der folgenden Varianten angegeben werden:

PyArg_Parse()

:c:func:`PyArg_Parse`

PyArg_Parse()

:c:func:`!PyArg_Parse`

Parsing arguments

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

Benutzerdefinierte Links

Ihr könnt auch eure eigenen intersphinx-Zuweisungen erstellen, wenn z.B. objects.inv Fehler aufweis wie bei Beautiful Soup.

Der Fehler kann mit korrigiert werden:

1. Installation of sphobjinv:

   $ python -m pip install sphobjinv
   

2. Dann könnt ihr die Originaldatei herunterladen mit:

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

3. Ändert die Sphinx-Konfiguration docs/conf.py:

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

4. Konvertiert die Datei in eine Textdatei:

   $ sphobjinv convert plain bs4_objects.inv bs4_objects.txt
   

5. Editiert die Textdatei, z.B.:

   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           -
   

   Diese Einträge können dann in einer Sphinx-Dokumentation mit referenziert werden:

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

   Siehe auch

   • Sphinx objects.inv v2 Syntax

6. Erstellt eine neue objects.inv-Datei:

   $ sphobjinv convert zlib bs4_objects.txt bs4_objects.txt
   

7. Erstellt eine neue Sphinx-Dokumentation:

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

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