sphinx.ext.linkcode – Externe Links zum Quellcode hinzufügen

Modulautor: Pauli Virtanen

Hinzugefügt in Version 1.2.

Diese Erweiterung betrachtet Ihre Objektbeschreibungen (.. class::, .. function:: usw.) und fügt externe Links zu Code hinzu, der irgendwo im Web gehostet wird. Die Absicht ist ähnlich der Erweiterung sphinx.ext.viewcode, geht aber davon aus, dass der Quellcode irgendwo im Internet zu finden ist.

In Ihrer Konfiguration müssen Sie eine Funktion linkcode_resolve angeben, die basierend auf dem Objekt eine URL zurückgibt.

Konfiguration

linkcode_resolve
Typ:
Callable[[str, dict[str, str]], str | None] | None
Standard:
None

Dies ist eine Funktion linkcode_resolve(domain, info), die die URL zum Quellcode für das Objekt in der gegebenen Domäne mit den gegebenen Informationen zurückgeben sollte.

Die Funktion sollte None zurückgeben, wenn kein Link hinzugefügt werden soll.

Das Argument domain gibt die Sprachdomäne an, in der sich das Objekt befindet. info ist ein Wörterbuch mit den folgenden Schlüsseln, die garantiert vorhanden sind (abhängig von der Domäne)

  • py: module (Name des Moduls), fullname (Name des Objekts)

  • c: names (Liste der Namen für das Objekt)

  • cpp: names (Liste der Namen für das Objekt)

  • javascript: object (Name des Objekts), fullname (Name des Elements)

Beispiel

def linkcode_resolve(domain, info):
    if domain != 'py':
        return None
    if not info['module']:
        return None
    filename = info['module'].replace('.', '/')
    return "https://somesite/sourcerepo/%s.py" % filename

Drittanbieter-Domänen

Unterstützung für andere Domänen kann durch Erweiterungen mit add_linkcode_domain() hinzugefügt werden. Zum Beispiel könnte eine Sphinx-Erweiterung, die eine php-Domäne bereitstellt, den folgenden Code verwenden, um linkcode zu unterstützen

from sphinx.ext.linkcode import add_linkcode_domain

def setup(app):
    add_linkcode_domain('php', ['namespace', 'class', 'fullname'])
sphinx.ext.linkcode.add_linkcode_domain(domain: str, keys: list[str], override: bool = False) → None[Quelle]

Registriert eine neue Liste von Schlüsseln, die für eine Domäne verwendet werden sollen.

Hinzugefügt in Version 8.2.