Anwendungs-API

Jede Sphinx-Erweiterung ist ein Python-Modul mit mindestens einer setup()-Funktion. Diese Funktion wird zur Initialisierungszeit mit einem Argument aufgerufen, dem Anwendungsobjekt, das den Sphinx-Prozess darstellt.

class sphinx.application.Sphinx[source]

Dieses Anwendungsobjekt verfügt über die öffentliche API, die in den folgenden Abschnitten beschrieben wird.

Erweiterungseinrichtung

Diese Methoden werden normalerweise in der setup()-Funktion einer Erweiterung aufgerufen.

Beispiele für die Verwendung der Sphinx-Erweiterungs-API finden Sie im Paket sphinx.ext.

Sphinx.setup_extension(extname: str) → None[source]

Importiert und richtet ein Sphinx-Erweiterungsmodul ein.

Lädt die Erweiterung, die durch den Modulnamen angegeben ist. Verwenden Sie dies, wenn Ihre Erweiterung die von einer anderen Erweiterung bereitgestellten Funktionen benötigt. Kein Vorgang, wenn sie zweimal aufgerufen wird.

static Sphinx.require_sphinx(version: tuple[int, int] | str) → None[source]

Überprüft die Sphinx-Version, falls angefordert.

Vergleicht version mit der Version des laufenden Sphinx und bricht den Build ab, wenn diese zu alt ist.

Parameter:

version – Die erforderliche Version im Format major.minor oder (major, minor).

Hinzugefügt in Version 1.0.

Geändert in Version 7.1: Der Typ von version erlaubt jetzt die Form (major, minor).

Sphinx.connect(event: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int = 500) → int[source]
Sphinx.connect(event: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int = 500) → int
Sphinx.connect(event: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int = 500) → int
Sphinx.connect(event: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int = 500) → int
Sphinx.connect(event: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int = 500) → int
Sphinx.connect(event: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int = 500) → int
Sphinx.connect(event: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int = 500) → int
Sphinx.connect(event: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int = 500) → int
Sphinx.connect(event: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int = 500) → int
Sphinx.connect(event: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int = 500) → int
Sphinx.connect(event: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int = 500) → int
Sphinx.connect(event: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int = 500) → int
Sphinx.connect(event: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int = 500) → int
Sphinx.connect(event: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int = 500) → int
Sphinx.connect(event: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int = 500) → int
Sphinx.connect(event: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int = 500) → int
Sphinx.connect(event: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-before-process-signature'], callback: _AutodocBeforeProcessSignatureListener, priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-process-signature'], callback: _AutodocProcessSignatureListener, priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-process-bases'], callback: _AutodocProcessBasesListener, priority: int = 500) → int
Sphinx.connect(event: Literal['autodoc-skip-member'], callback: _AutodocSkipMemberListener, priority: int = 500) → int
Sphinx.connect(event: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int = 500) → int
Sphinx.connect(event: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int = 500) → int
Sphinx.connect(event: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int = 500) → int
Sphinx.connect(event: str, callback: Callable[..., Any], priority: int = 500) → int

Registriert callback, um aufgerufen zu werden, wenn event ausgelöst wird.

Details zu verfügbaren Kernereignissen und den Argumenten von Callback-Funktionen finden Sie unter API für Ereignis-Callbacks.

Parameter:

  • event – Der Name des Zielereignisses

  • callback – Callback-Funktion für das Ereignis

  • priority – Die Priorität des Callbacks. Die Callbacks werden in aufsteigender Reihenfolge der Priorität aufgerufen.

Gibt zurück:

Eine Listener-ID. Sie kann für disconnect() verwendet werden.

Geändert in Version 3.0: Unterstützung für priority

Sphinx.disconnect(listener_id: int) → None[source]

Registriert den Callback durch listener_id ab.

Parameter:

listener_id – Eine Listener-ID, die von connect() zurückgegeben wird

Sphinx.add_builder(builder: type[Builder], override: bool = False) → None[source]

Registriert einen neuen Builder.

Parameter:

  • builder – Eine Builder-Klasse

  • override – Wenn wahr, wird der Builder zwangsweise installiert, auch wenn bereits ein anderer Builder mit demselben Namen installiert ist

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_config_value(name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '') → None[source]

Registriert einen Konfigurationswert.

Dies ist notwendig, damit Sphinx neue Werte erkennt und entsprechende Standardwerte setzt.

Parameter:

  • name – Der Name des Konfigurationswertes. Es wird empfohlen, den Erweiterungsnamen voranzustellen (z.B. html_logo, epub_title).

  • default – Der Standardwert der Konfiguration.

  • rebuild –

    Die Bedingung für den Neuaufbau. Es muss einer der folgenden Werte sein:

    • 'env', wenn eine Änderung der Einstellung erst beim Parsen eines Dokuments wirksam wird – das bedeutet, dass die gesamte Umgebung neu aufgebaut werden muss.

    • 'html', wenn eine Änderung der Einstellung einen vollständigen Neuaufbau der HTML-Dokumente erfordert.

    • '', wenn eine Änderung der Einstellung keinen besonderen Neuaufbau erfordert.

  • types – Der Typ des Konfigurationswertes. Es kann eine Liste von Typen angegeben werden. Zum Beispiel wird [str] verwendet, um eine Konfiguration zu beschreiben, die Zeichenkettenwerte annimmt.

  • description – Eine kurze Beschreibung des Konfigurationswertes.

Geändert in Version 0.4: Wenn der default-Wert eine aufrufbare Funktion ist, wird diese mit dem Konfigurationsobjekt als Argument aufgerufen, um den Standardwert zu erhalten. Dies kann verwendet werden, um Konfigurationswerte zu implementieren, deren Standardwert von anderen Werten abhängt.

Geändert in Version 0.6: rebuild wurde von einem einfachen booleschen Wert (entspricht '' oder 'env') zu einem String geändert. Boolesche Werte werden jedoch weiterhin akzeptiert und intern konvertiert.

Hinzugefügt in Version 1.4: Der Parameter types.

Hinzugefügt in Version 7.4: Der Parameter description.

Sphinx.add_event(name: str) → None[source]

Registriert ein Ereignis namens name.

Dies ist notwendig, um es auslösen zu können.

Parameter:

name – Der Name des Ereignisses

Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) → None[source]

Registriert oder überschreibt eine Docutils-Übersetzerklasse.

Dies wird verwendet, um einen benutzerdefinierten Ausgabeübersetzer zu registrieren oder einen integrierten Übersetzer zu ersetzen. Dies ermöglicht es Erweiterungen, einen benutzerdefinierten Übersetzer zu verwenden und benutzerdefinierte Knoten für den Übersetzer zu definieren (siehe add_node()).

Parameter:

  • name – Der Name des Builders für den Übersetzer

  • translator_class – Eine Übersetzerklasse

  • override – Wenn true, wird der Übersetzer erzwungen installiert, auch wenn bereits ein anderer Übersetzer mit demselben Namen installiert ist

Hinzugefügt in Version 1.3.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: _NodeHandlerPair) → None[source]

Registriert eine Docutils-Knotenklasse.

Dies ist für die Docutils-Interna notwendig. Es kann auch zukünftig verwendet werden, um Knoten in den geparsten Dokumenten zu validieren.

Parameter:

  • node – Eine Knotenklasse

  • kwargs – Besucherfunktionen für jeden Builder (siehe unten)

  • override – Wenn true, wird der Knoten erzwungen installiert, auch wenn bereits ein anderer Knoten mit demselben Namen installiert ist

Besucherfunktionen für die Sphinx HTML-, LaTeX-, Text- und Manpage-Writer können als Schlüsselwortargumente übergeben werden: Das Schlüsselwort sollte einer oder mehrere der folgenden sein: 'html', 'latex', 'text', 'man', 'texinfo' oder andere unterstützte Übersetzer, der Wert ein 2-Tupel aus visit und depart Methoden. depart kann None sein, wenn die visit Funktion docutils.nodes.SkipNode auslöst. Beispiel

class math(docutils.nodes.Element): ...

def visit_math_html(self, node):
    self.body.append(self.starttag(node, 'math'))

def depart_math_html(self, node):
    self.body.append('</math>')

app.add_node(math, html=(visit_math_html, depart_math_html))

Offensichtlich werden Übersetzer, für die Sie keine Besuchermethoden angeben, beim Auftreten des Knotens im zu übersetzenden Dokument fehlschlagen.

Geändert in Version 0.5: Unterstützung für Schlüsselwortargumente zur Übergabe von Besuchfunktionen hinzugefügt.

Sphinx.add_enumerable_node(node: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[_NodeHandler, _NodeHandler]) → None[source]

Registriert eine Docutils-Knotenklasse als Numfig-Ziel.

Sphinx nummeriert den Knoten automatisch. Danach können Benutzer ihn mit numref referenzieren.

Parameter:

  • node – Eine Knotenklasse

  • figtype – Der Typ der aufzählbaren Knoten. Jeder figtype hat individuelle Nummerierungssequenzen. Als System-Figtypen sind figure, table und code-block definiert. Es ist möglich, benutzerdefinierte Knoten zu diesen Standard-Figtypen hinzuzufügen. Es ist auch möglich, neue benutzerdefinierte Figtypen zu definieren, wenn ein neuer Figtyp angegeben wird.

  • title_getter – Eine Getter-Funktion, um den Titel des Knotens zu erhalten. Sie nimmt eine Instanz des aufzählbaren Knotens entgegen und muss dessen Titel als String zurückgeben. Der Titel wird als Standardtitel für Referenzen für ref verwendet. Standardmäßig sucht Sphinx nach docutils.nodes.caption oder docutils.nodes.title im Knoten als Titel.

  • kwargs – Besucherfunktionen für jeden Builder (wie bei add_node())

  • override – Wenn true, wird der Knoten erzwungen installiert, auch wenn bereits ein anderer Knoten mit demselben Namen installiert ist

Hinzugefügt in Version 1.4.

Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) → None[source]

Registriert eine Docutils-Direktive.

Parameter:

  • name – Der Name der Direktive

  • cls – Eine Direktivenklasse

  • override – Wenn false, wird sie nicht installiert, wenn bereits eine andere Direktive mit demselben Namen installiert ist. Wenn true, wird die Direktive bedingungslos installiert.

Zum Beispiel würde eine benutzerdefinierte Direktive namens my-directive wie folgt hinzugefügt werden:

from docutils.parsers.rst import Directive, directives

class MyDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        pass

def setup(app):
    app.add_directive('my-directive', MyDirective)

Weitere Details finden Sie in der Docutils-Dokumentation.

Geändert in Version 0.6: Docutils 0.5-Stil Direktivenklassen werden jetzt unterstützt.

Geändert in Version 1.8: Die Unterstützung für Docutils 0.4-Stil (funktionsbasierte) Direktiven ist veraltet.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_role(name: str, role: Any, override: bool = False) → None[source]

Registriert eine Docutils-Rolle.

Parameter:

  • name – Der Name der Rolle

  • role – Eine Rollenfunktion

  • override – Wenn false, wird sie nicht installiert, wenn bereits eine andere Rolle mit demselben Namen installiert ist. Wenn true, wird die Rolle bedingungslos installiert.

Weitere Details zu Rollenfunktionen finden Sie in der Docutils-Dokumentation.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) → None[source]

Registriert eine generische Docutils-Rolle.

Registriert eine Docutils-Rolle, die nichts anderes tut, als ihren Inhalt in den durch nodeclass gegebenen Knoten zu verpacken.

Parameter:

override – Wenn false, wird sie nicht installiert, wenn bereits eine andere Rolle mit demselben Namen installiert ist. Wenn true, wird die Rolle bedingungslos installiert.

Hinzugefügt in Version 0.6.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_domain(domain: type[Domain], override: bool = False) → None[source]

Registriert eine Domäne.

Parameter:

  • domain – Eine Domänenklasse

  • override – Wenn false, wird sie nicht installiert, wenn bereits eine andere Domäne mit demselben Namen installiert ist. Wenn true, wird die Domäne bedingungslos installiert.

Hinzugefügt in Version 1.0.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[Directive], override: bool = False) → None[source]

Registriert eine Docutils-Direktive in einer Domäne.

Wie add_directive(), aber die Direktive wird der Domäne mit dem Namen domain hinzugefügt.

Parameter:

  • domain – Der Name der Ziel-Domäne

  • name – Ein Name der Direktive

  • cls – Eine Direktivenklasse

  • override – Wenn false, wird sie nicht installiert, wenn bereits eine andere Direktive mit demselben Namen installiert ist. Wenn true, wird die Direktive bedingungslos installiert.

Hinzugefügt in Version 1.0.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) → None[source]

Registriert eine Docutils-Rolle in einer Domäne.

Wie add_role(), aber die Rolle wird der Domäne mit dem Namen domain hinzugefügt.

Parameter:

  • domain – Der Name der Ziel-Domäne

  • name – Der Name der Rolle

  • role – Die Rollenfunktion

  • override – Wenn false, wird sie nicht installiert, wenn bereits eine andere Rolle mit demselben Namen installiert ist. Wenn true, wird die Rolle bedingungslos installiert.

Hinzugefügt in Version 1.0.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) → None[source]

Registriert einen benutzerdefinierten Index für eine Domäne.

Fügt der Domäne mit dem Namen domain eine benutzerdefinierte index-Klasse hinzu.

Parameter:

  • domain – Der Name der Ziel-Domäne

  • index – Die Indexklasse

  • override – Wenn false, wird sie nicht installiert, wenn bereits ein anderer Index mit demselben Namen installiert ist. Wenn true, wird der Index bedingungslos installiert.

Hinzugefügt in Version 1.0.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable[[BuildEnvironment, str, addnodes.desc_signature], str] | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence[Field] = (), override: bool = False) → None[source]

Registriert einen neuen Objekttyp.

Diese Methode ist eine sehr bequeme Möglichkeit, einen neuen Objekttyp hinzuzufügen, der referenziert werden kann. Sie wird Folgendes tun:

  • Erzeugt eine neue Direktive (genannt directivename) zur Dokumentation eines Objekts. Sie fügt automatisch Indexeinträge hinzu, wenn indextemplate nicht leer ist; wenn angegeben, muss es genau eine Instanz von %s enthalten. Sehen Sie sich das folgende Beispiel an, wie die Vorlage interpretiert wird.

  • Erzeugt eine neue Rolle (genannt rolename) zur Querverweisung auf diese Objektbeschreibungen.

  • Wenn Sie parse_node angeben, muss es sich um eine Funktion handeln, die einen String und einen Docutils-Knoten entgegennimmt und den Knoten mit Kindern, die aus dem String geparst wurden, füllen muss. Sie muss dann den Namen des Elements zurückgeben, das für Querverweise und Indexeinträge verwendet werden soll. Sehen Sie sich die conf.py-Datei in der Quelle dieser Dokumentation für ein Beispiel an.

  • Der objname (wenn nicht angegeben, wird er standardmäßig directivename sein) benennt den Typ des Objekts. Er wird beim Auflisten von Objekten verwendet, z.B. in Suchergebnissen.

Zum Beispiel, wenn Sie diesen Aufruf in einer benutzerdefinierten Sphinx-Erweiterung haben

app.add_object_type('directive', 'dir', 'pair: %s; directive')

können Sie diese Markierung in Ihren Dokumenten verwenden

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

Für die Direktive wird ein Indexeintrag generiert, als ob Sie hinzugefügt hätten:

.. index:: pair: function; directive

Der Referenzknoten wird von der Klasse literal sein (er wird also in einer proportionalen Schriftart gerendert, wie es für Code angemessen ist), es sei denn, Sie geben das Argument ref_nodeclass an, das eine Docutils-Knotenklasse sein muss. Am nützlichsten sind docutils.nodes.emphasis oder docutils.nodes.strong – Sie können auch docutils.nodes.generated verwenden, wenn Sie keine weitere Textdekoration wünschen. Wenn der Text als Literal behandelt werden soll (z.B. keine Smart-Quote-Ersetzung), aber keine Schreibmaschinenformatierung aufweisen soll, verwenden Sie sphinx.addnodes.literal_emphasis oder sphinx.addnodes.literal_strong.

Für den Rolleninhalt haben Sie die gleichen syntaktischen Möglichkeiten wie für Standard-Sphinx-Rollen (siehe Syntax).

Wenn override True ist, wird der gegebene object_type erzwungen installiert, auch wenn bereits ein object_type mit demselben Namen installiert ist.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', override: bool = False) → None[source]

Registriert einen neuen Crossref-Objekttyp.

Diese Methode ähnelt stark add_object_type(), mit der Ausnahme, dass die generierte Direktive leer sein muss und keine Ausgabe erzeugt.

Das bedeutet, dass Sie semantische Ziele zu Ihren Quellen hinzufügen und mit benutzerdefinierten Rollen anstelle generischer (wie ref) darauf verweisen können. Beispielaufruf

app.add_crossref_type(
    'topic', 'topic', 'single: %s', docutils.nodes.emphasis
)

Beispielnutzung

.. topic:: application API

The application API
-------------------

Some random text here.

See also :topic:`this section <application API>`.

(Natürlich muss das Element nach der topic-Direktive keine Sektion sein.)

Parameter:

override – Wenn falsch, wird sie nicht installiert, wenn bereits ein anderer Crossref-Typ mit demselben Namen installiert ist. Wenn wahr, wird der Crossref-Typ bedingungslos installiert.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_transform(transform: type[Transform]) → None[source]

Registriert eine Docutils-Transformation, die nach dem Parsen angewendet werden soll.

Fügt die Standard-Docutils-Unterklasse Transform transform zur Liste der Transformationen hinzu, die angewendet werden, nachdem Sphinx ein reST-Dokument geparst hat.

Parameter:

transform – Eine Transform-Klasse

Prioritätsbereichskategorien für Sphinx-Transformationen

Priorität

Hauptzweck in Sphinx

0-99

Korrigiert ungültige Knoten durch Docutils. Übersetzt einen Doctree.

100-299

Vorbereitung

300-399

früh

400-699

Haupt

700-799

Nachbearbeitung. Frist für die Änderung von Text und Referenzierung.

800-899

Sammelt Referenzierungs- und referenzierte Knoten. Domänenverarbeitung.

900-999

Finalisierung und Bereinigung.

refs: Transform Priority Range Categories

Sphinx.add_post_transform(transform: type[Transform]) → None[source]

Registriert eine Docutils-Transformation, die vor dem Schreiben angewendet werden soll.

Fügt die Standard-Docutils-Unterklasse Transform transform zur Liste der Transformationen hinzu, die angewendet werden, bevor Sphinx ein Dokument schreibt.

Parameter:

transform – Eine Transform-Klasse

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) → None[source]

Registriert eine JavaScript-Datei, die in die HTML-Ausgabe aufgenommen werden soll.

Parameter:

  • filename – Der Name einer JavaScript-Datei, die die Standard-HTML-Vorlage aufnehmen wird. Sie muss relativ zum statischen HTML-Pfad oder eine vollständige URI mit Schema sein, oder None. Der Wert None wird verwendet, um ein Inline-Tag <script> zu erstellen. Siehe die Beschreibung von kwargs unten.

  • priority – Dateien werden in aufsteigender Reihenfolge der Priorität aufgenommen. Wenn mehrere JavaScript-Dateien die gleiche Priorität haben, werden diese Dateien in der Reihenfolge ihrer Registrierung aufgenommen. Siehe Liste der "Prioritätsbereiche für JavaScript-Dateien" unten.

  • loading_method – Die Lademethode für die JavaScript-Datei. Es sind entweder 'async' oder 'defer' erlaubt.

  • kwargs – Zusätzliche Schlüsselwortargumente werden als Attribute des <script>-Tags aufgenommen. Wenn das spezielle Schlüsselwortargument body angegeben wird, wird sein Wert als Inhalt des <script>-Tags hinzugefügt.

Beispiel

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', loading_method='async')
# => <script src="_static/example.js" async="async"></script>

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>
Prioritätsbereich für JavaScript-Dateien

Priorität

Hauptzweck in Sphinx

200

Standardpriorität für integrierte JavaScript-Dateien

500

Standardpriorität für Erweiterungen

800

Standardpriorität für html_js_files

Eine JavaScript-Datei kann der spezifischen HTML-Seite hinzugefügt werden, wenn eine Erweiterung diese Methode beim html-page-context-Ereignis aufruft.

Hinzugefügt in Version 0.5.

Geändert in Version 1.8: Umbenannt von app.add_javascript(). Und es erlaubt Schlüsselwortargumente als Attribute des Script-Tags.

Geändert in Version 3.5: Nimmt das Prioritätsargument an. Erlaubt das Hinzufügen einer JavaScript-Datei zur spezifischen Seite.

Geändert in Version 4.4: Nimmt das Argument loading_method an. Ermöglicht die Änderung der Lademethode der JavaScript-Datei.

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None[source]

Registriert eine Stylesheet-Datei, die in die HTML-Ausgabe aufgenommen werden soll.

Parameter:

  • filename – Der Name einer CSS-Datei, die die Standard-HTML-Vorlage aufnehmen wird. Sie muss relativ zum statischen HTML-Pfad oder eine vollständige URI mit Schema sein.

  • priority – Dateien werden in aufsteigender Reihenfolge der Priorität aufgenommen. Wenn mehrere CSS-Dateien die gleiche Priorität haben, werden diese Dateien in der Reihenfolge ihrer Registrierung aufgenommen. Siehe Liste der "Prioritätsbereiche für CSS-Dateien" unten.

  • kwargs – Zusätzliche Schlüsselwortargumente werden als Attribute des <link>-Tags aufgenommen.

Beispiel

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />
Prioritätsbereich für CSS-Dateien

Priorität

Hauptzweck in Sphinx

200

Standardpriorität für integrierte CSS-Dateien

500

Standardpriorität für Erweiterungen

800

Standardpriorität für html_css_files

Eine CSS-Datei kann der spezifischen HTML-Seite hinzugefügt werden, wenn eine Erweiterung diese Methode beim html-page-context-Ereignis aufruft.

Hinzugefügt in Version 1.0.

Geändert in Version 1.6: Optionale Attribute alternate und/oder title können mit den Argumenten alternate (ein Boolean) und title (ein String) übergeben werden. Standardmäßig gibt es keinen Titel und alternate = False. Weitere Informationen finden Sie in der Dokumentation.

Geändert in Version 1.8: Umbenannt von app.add_stylesheet(). Und es erlaubt Schlüsselwortargumente als Attribute des Link-Tags.

Geändert in Version 3.5: Nimmt das Prioritätsargument an. Ermöglicht das Hinzufügen einer CSS-Datei zur spezifischen Seite.

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) → None[source]

Registriert ein Paket, das in den LaTeX-Quellcode aufgenommen werden soll.

Fügt packagename zur Liste der Pakete hinzu, die der LaTeX-Quellcode einschließen wird. Wenn Sie options angeben, wird dies zur Deklaration usepackage verwendet. Wenn Sie after_hyperref wahr setzen, wird das Paket nach dem Paket hyperref geladen.

app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

Hinzugefügt in Version 1.3.

Hinzugefügt in Version 3.1: Option after_hyperref.

Sphinx.add_lexer(alias: str, lexer: type[Lexer]) → None[source]

Registriert einen neuen Lexer für Quellcode.

Verwendet lexer, um Codeblöcke mit der angegebenen Sprach-alias hervorzuheben.

Hinzugefügt in Version 0.6.

Geändert in Version 2.1: Nimmt eine Lexer-Klasse als Argument an.

Geändert in Version 4.0: Unterstützung für Lexer-Instanzen als Argument entfernt.

Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) → None[source]

Registriert eine neue Documenter-Klasse für die autodoc-Erweiterung.

Fügt cls als neue Documenter-Klasse für die Erweiterung sphinx.ext.autodoc hinzu. Sie muss eine Unterklasse von sphinx.ext.autodoc.Documenter sein. Dies ermöglicht die automatische Dokumentation neuer Objekttypen. Schauen Sie sich den Quellcode des Autodoc-Moduls an, um Beispiele für das Unterklassen von Documenter zu finden.

Wenn override True ist, wird die angegebene cls zwangsweise installiert, auch wenn bereits ein Documenter mit demselben Namen installiert ist.

Siehe Entwickeln von autodoc-Erweiterungen.

Hinzugefügt in Version 0.6.

Geändert in Version 2.2: Schlüsselwort override hinzugefügt.

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) → None[source]

Registriert eine neue getattr-ähnliche Funktion für die autodoc-Erweiterung.

Fügt getter, eine Funktion mit einer Schnittstelle, die mit dem integrierten getattr() kompatibel ist, als autodoc-Attribut-Getter für Instanzen von typ hinzu. Alle Fälle, in denen autodoc ein Attribut eines Typs abrufen muss, werden dann von dieser Funktion anstelle von getattr() behandelt.

Hinzugefügt in Version 0.6.

Sphinx.add_search_language(cls: type[SearchLanguage]) → None[source]

Registriert eine neue Sprache für den HTML-Suchindex.

Fügt cls, eine Unterklasse von sphinx.search.SearchLanguage, als unterstützte Sprache für den Aufbau des HTML-Volltextsuchindex hinzu. Die Klasse muss ein lang-Attribut haben, das die Sprache angibt, für die sie verwendet werden soll. Siehe html_search_language.

Hinzugefügt in Version 1.1.

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) → None[source]

Registriert eine Endung von Quelldateien.

Gleich wie source_suffix. Benutzer können dies mit der Konfigurationseinstellung überschreiben.

Parameter:

override – Wenn falsch, wird sie nicht installiert, wenn die gleiche Endung bereits installiert ist. Wenn wahr, wird die Endung bedingungslos installiert.

Hinzugefügt in Version 1.8.

Sphinx.add_source_parser(parser: type[Parser], override: bool = False) → None[source]

Registriert eine Parser-Klasse.

Parameter:

override – Wenn falsch, wird sie nicht installiert, wenn bereits ein anderer Parser für die gleiche Endung installiert ist. Wenn wahr, wird der Parser bedingungslos installiert.

Hinzugefügt in Version 1.4.

Geändert in Version 1.8: Das Argument suffix ist veraltet. Es akzeptiert nur das Argument parser. Verwenden Sie die API add_source_suffix(), um die Endung zu registrieren.

Geändert in Version 1.8: override Keyword hinzugefügt.

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None[source]

Registriert eine Environment-Collector-Klasse.

Siehe Environment Collector API.

Hinzugefügt in Version 1.6.

Sphinx.add_html_theme(name: str, theme_path: str | os.PathLike[str]) → None[source]

Registriert ein HTML-Theme.

Der name ist ein Name des Themes und theme_path ist ein vollständiger Pfad zum Theme (siehe: Verteilen Sie Ihr Theme als Python-Paket).

Hinzugefügt in Version 1.6.

Sphinx.add_html_math_renderer(name: str, inline_renderers: _MathsInlineRenderers | None = None, block_renderers: _MathsBlockRenderers | None = None) → None[source]

Registriert einen Mathematik-Renderer für HTML.

Der name ist der Name des Mathematik-Renderers. Sowohl inline_renderers als auch block_renderers werden als Besucherfunktionen für den HTML-Writer verwendet: die ersteren für den Inline-Mathematik-Knoten (nodes.math), die letzteren für den Block-Mathematik-Knoten (nodes.math_block). Bezüglich Besucherfunktionen siehe add_node() für Details.

Hinzugefügt in Version 1.8.

Sphinx.add_message_catalog(catalog: str, locale_dir: str | os.PathLike[str]) → None[source]

Registriert einen Nachrichten-Katalog.

Parameter:

  • catalog – Der Name des Katalogs

  • locale_dir – Der Basis-Pfad des Nachrichten-Katalogs

Weitere Details finden Sie unter sphinx.locale.get_translation().

Hinzugefügt in Version 1.8.

Sphinx.is_parallel_allowed(typ: str) → bool[source]

Prüft, ob parallele Verarbeitung erlaubt ist oder nicht.

Parameter:

typ – Eine Art der Verarbeitung; 'read' oder 'write'.

Sphinx.set_html_assets_policy(policy: Literal['always', 'per_page']) → None[source]

Legt die Richtlinie für die Einbindung von Assets in HTML-Seiten fest.

  • always: bindet die Assets in allen Seiten ein

  • per_page: bindet die Assets nur in den Seiten ein, wo sie verwendet werden

exception sphinx.application.ExtensionError

Alle diese Methoden lösen diese Ausnahme aus, wenn bei der Extension API etwas schief gelaufen ist.

Ereignisse auslösen

Aufmerksamkeit

Entwickler von Erweiterungen sollten es vorziehen, direkt den Ereignismanager (events) über EventManager.emit() und EventManager.emit_firstresult() zu verwenden, die das gleiche Verhalten wie die folgenden Methoden haben.

class sphinx.application.Sphinx[source]
emit(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[Any][source]

Löst das Ereignis event aus und übergibt arguments an die Callback-Funktionen.

Gibt die Rückgabewerte aller Callbacks als Liste zurück. Rufen Sie keine Kern-Sphinx-Ereignisse in Erweiterungen auf!

Parameter:

  • event – Der Name des auszulösenden Ereignisses

  • args – Die Argumente für das Ereignis

  • allowed_exceptions – Die Liste der Ausnahmen, die in den Callbacks erlaubt sind

Geändert in Version 3.1: allowed_exceptions hinzugefügt, um Ausnahmen weiterzuleiten

emit_firstresult(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any[source]

Löst das Ereignis event aus und übergibt arguments an die Callback-Funktionen.

Gibt das Ergebnis des ersten Callbacks zurück, der nicht None zurückgibt.

Parameter:

  • event – Der Name des auszulösenden Ereignisses

  • args – Die Argumente für das Ereignis

  • allowed_exceptions – Die Liste der Ausnahmen, die in den Callbacks erlaubt sind

Hinzugefügt in Version 0.5.

Geändert in Version 3.1: allowed_exceptions hinzugefügt, um Ausnahmen weiterzuleiten

Sphinx Laufzeitinformationen

Das Anwendungsobjekt stellt auch Laufzeitinformationen als Attribute bereit.

Sphinx.project

Zielprojekt. Siehe Project.

Sphinx.srcdir

Quellverzeichnis.

Sphinx.confdir

Verzeichnis, das conf.py enthält.

Sphinx.doctreedir

Verzeichnis zum Speichern von gepickelten Doctrees.

Sphinx.outdir

Verzeichnis zum Speichern des erstellten Dokuments.

Sphinx.fresh_env_used

True/False, ob für diesen Build eine neue Umgebung erstellt wurde, oder None, wenn die Umgebung noch nicht initialisiert wurde.

Sphinx Kern-Ereignisse

Hinweis

Verschoben nach API für Event-Callbacks.

Prüfen der Sphinx-Version

Verwenden Sie dies, um Ihre Erweiterung an API-Änderungen in Sphinx anzupassen.

sphinx.version_info: Final = (9, 0, 1, 'beta', 0)

Versionsinformationen für eine bessere programmatische Nutzung.

Ein Tupel aus fünf Elementen; für Sphinx-Version 1.2.1 beta 3 wäre dies (1, 2, 1, 'beta', 3). Das vierte Element kann einer der folgenden Werte sein: alpha, beta, rc, final. final hat immer 0 als letztes Element.

Hinzugefügt in Version 1.2: Vor Version 1.2 prüfen Sie die Zeichenkette sphinx.__version__.

Das Config-Objekt

class sphinx.config.Config(config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None)[source]

Abstraktion der Konfigurationsdatei.

Das Config-Objekt macht die Werte aller Konfigurationsoptionen als Attribute verfügbar.

Es wird über die Attribute Sphinx.config und sphinx.environment.BuildEnvironment.config bereitgestellt. Um beispielsweise den Wert von language abzurufen, verwenden Sie entweder app.config.language oder env.config.language.

Die Template-Bridge

class sphinx.application.TemplateBridge[source]

Diese Klasse definiert die Schnittstelle für eine "Template-Bridge", d.h. eine Klasse, die Templates basierend auf einem Templatenamen und einem Kontext rendert.

init(builder: Builder, theme: Theme | None = None, dirs: list[str] | None = None) → None[source]

Wird vom Builder aufgerufen, um das Templatesystem zu initialisieren.

builder ist das Builder-Objekt; Sie möchten wahrscheinlich den Wert von builder.config.templates_path betrachten.

theme ist ein sphinx.theming.Theme Objekt oder None; im letzteren Fall kann dirs eine Liste von festen Verzeichnissen sein, in denen nach Templates gesucht werden soll.

newest_template_mtime() → float[source]

Wird vom Builder aufgerufen, um festzustellen, ob Ausgabedateien aufgrund von Template-Änderungen veraltet sind. Gibt die mtime der neuesten Template-Datei zurück, die geändert wurde. Die Standardimplementierung gibt 0 zurück.

render(template: str, context: dict[str, Any]) → None[source]

Wird vom Builder aufgerufen, um ein Template, das als Dateiname übergeben wird, mit einem angegebenen Kontext (einem Python-Dictionary) zu rendern.

render_string(template: str, context: dict[str, Any]) → str[source]

Wird vom Builder aufgerufen, um ein Template, das als Zeichenkette übergeben wird, mit einem angegebenen Kontext (einem Python-Dictionary) zu rendern.

Ausnahmen

exception sphinx.errors.SphinxError[source]

Basisklasse für Sphinx-Fehler.

Dies ist die Basisklasse für "schöne" Ausnahmen. Wenn eine solche Ausnahme ausgelöst wird, bricht Sphinx den Build ab und präsentiert dem Benutzer die Ausnahmekategorie und die Nachricht.

Erweiterungen werden ermutigt, sich von dieser Ausnahme für ihre benutzerdefinierten Fehler abzuleiten.

Ausnahmen, die *nicht* von SphinxError abgeleitet sind, werden als unerwartet behandelt und dem Benutzer mit einem Teil des Tracebacks angezeigt (und der vollständige Traceback wird in einer temporären Datei gespeichert).

category

Beschreibung der Ausnahmekategorie, die bei der Konvertierung der Ausnahme in eine Zeichenkette verwendet wird ("Kategorie: Nachricht"). Sollte in Unterklassen entsprechend gesetzt werden.

exception sphinx.errors.ConfigError[source]

Konfigurationsfehler.

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)[source]

Erweiterungsfehler.

exception sphinx.errors.ThemeError[source]

Theme-Fehler.

exception sphinx.errors.VersionRequirementError[source]

Inkompatibler Sphinx-Versionsfehler.