Dienstprogramme

Sphinx bietet Dienstprogrammklassen und -funktionen zur Entwicklung von Erweiterungen.

Basisklassen für Komponenten

Diese Basisklassen sind nützlich, um Ihren Erweiterungen einfachen Zugriff auf Sphinx-Komponenten zu ermöglichen (z. B. Config, BuildEnvironment und so weiter).

Hinweis

Die Unterklassen davon funktionieren möglicherweise nicht mit reinem Docutils, da sie stark an Sphinx gekoppelt sind.

class sphinx.transforms.SphinxTransform(document, startnode=None)[Quelle]

Eine Basisklasse von Transforms.

Im Vergleich zu docutils.transforms.Transform verbessert diese Klasse die Zugänglichkeit zu Sphinx-APIs.

property app: Sphinx

Referenz auf das Sphinx-Objekt.

property config: Config

Referenz auf das Config-Objekt.

property env: BuildEnvironment

Referenz auf das BuildEnvironment-Objekt.

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)[Quelle]

Eine Basisklasse von Post-Transforms.

Post-Transforms werden aufgerufen, um das Dokument zur Umstrukturierung für die Ausgabe zu modifizieren. Sie lösen Referenzen auf, konvertieren Bilder, führen spezielle Transformationen für jedes Ausgabeformat durch und so weiter. Diese Klasse hilft bei der Implementierung dieser Post-Transforms.

apply(**kwargs: Any) → None[Quelle]

Überschreiben Sie dies, um den Transform auf den Dokumentenbaum anzuwenden.

is_supported() → bool[Quelle]

Prüfen Sie, ob dieser Transform für den aktuellen Builder funktioniert.

run(**kwargs: Any) → None[Quelle]

Hauptmethode von Post-Transforms.

Unterklassen sollten diese Methode anstelle von apply() überschreiben.

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[Quelle]

Eine Basisklasse für Sphinx-Direktiven.

Diese Klasse bietet Hilfsmethoden für Sphinx-Direktiven.

Hinzugefügt in Version 1.8.

Hinweis

Die Unterklassen dieser Klasse funktionieren möglicherweise nicht mit Docutils. Diese Klasse ist stark an Sphinx gekoppelt.

get_location() → str[Quelle]

Aktuelle Standortinformationen für die Protokollierung abrufen.

Hinzugefügt in Version 4.2.

get_source_info() → tuple[str, int][Quelle]

Quelle und Zeilennummer abrufen.

Hinzugefügt in Version 3.0.

parse_content_to_nodes(allow_section_headings: bool = False) → list[Node][Quelle]

Den Inhalt der Direktive in Knoten parsen.

Parameter:

allow_section_headings – Sind Überschriften (Abschnitte) im Inhalt der Direktive erlaubt? Beachten Sie, dass diese Option die üblichen Prüfungen von Docutils auf die Doctree-Struktur umgeht und Missbrauch dieser Option zu einem inkohärenten Doctree führen kann. In Docutils sollten Abschnittsknoten nur Kinder von Structural-Knoten sein, was document, section und sidebar-Knoten einschließt.

Hinzugefügt in Version 7.4.

parse_inline(text: str, *, lineno: int = -1) → tuple[list[Node], list[system_message]][Quelle]

text als Inline-Elemente parsen.

Parameter:

  • text – Der zu parsenden Text, der eine einzelne Zeile oder ein Absatz sein sollte. Dieser darf keine strukturellen Elemente (Überschriften, Übergänge, Direktiven usw.) enthalten.

  • lineno – Die Zeilennummer, an der der interpretierte Text beginnt.

Gibt zurück:

Eine Liste von Knoten (Text und Inline-Elemente) und eine Liste von system_messages.

Hinzugefügt in Version 7.4.

parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) → list[Node][Quelle]

text in Knoten parsen.

Parameter:

  • text – Text in Zeichenkettenform. StringList wird ebenfalls akzeptiert.

  • allow_section_headings – Sind Überschriften (Abschnitte) in text erlaubt? Beachten Sie, dass diese Option die üblichen Prüfungen von Docutils auf die Doctree-Struktur umgeht und Missbrauch dieser Option zu einem inkohärenten Doctree führen kann. In Docutils sollten Abschnittsknoten nur Kinder von Structural-Knoten sein, was document, section und sidebar-Knoten einschließt.

  • offset – Der Offset des Inhalts.

Hinzugefügt in Version 7.4.

set_source_info(node: Node) → None[Quelle]

Quellen- und Zeilennummer für den Knoten setzen.

Hinzugefügt in Version 2.1.

property config: Config

Referenz auf das Config-Objekt.

Hinzugefügt in Version 1.8.

property env: BuildEnvironment

Referenz auf das BuildEnvironment-Objekt.

Hinzugefügt in Version 1.8.

class sphinx.util.docutils.SphinxRole[Quelle]

Eine Basisklasse für Sphinx-Rollen.

Diese Klasse bietet Hilfsmethoden für Sphinx-Rollen.

Hinzugefügt in Version 2.0.

Hinweis

Die Unterklassen dieser Klasse funktionieren möglicherweise nicht mit Docutils. Diese Klasse ist stark an Sphinx gekoppelt.

get_location() → str[Quelle]

Aktuelle Standortinformationen für die Protokollierung abrufen.

Hinzugefügt in Version 4.2.

property config: Config

Referenz auf das Config-Objekt.

Hinzugefügt in Version 2.0.

content: Sequence[str]

Eine Liste von Zeichenketten, der Direktiveninhalt zur Anpassung (aus der Direktive „role“).

property env: BuildEnvironment

Referenz auf das BuildEnvironment-Objekt.

Hinzugefügt in Version 2.0.

inliner: Inliner

Das docutils.parsers.rst.states.Inliner-Objekt.

lineno: int

Die Zeilennummer, an der der interpretierte Text beginnt.

name: str

Der Rollenname, der tatsächlich im Dokument verwendet wird.

options: dict[str, Any]

Ein Wörterbuch von Direktivenoptionen zur Anpassung (aus der Direktive „role“).

rawtext: str

Eine Zeichenkette, die den gesamten interpretierten Textinhalt enthält.

text: str

Der interpretierte Textinhalt.

class sphinx.util.docutils.ReferenceRole[Quelle]

Eine Basisklasse für Referenzrollen.

Die Referenzrollen können den Stil link title <target> als Text für die Rolle akzeptieren. Das geparste Ergebnis; Linktitel und Ziel werden in self.title und self.target gespeichert.

Hinzugefügt in Version 2.0.

disabled: bool

Ein boolescher Wert, der angibt, dass die Referenz deaktiviert ist.

has_explicit_title: bool

Ein boolescher Wert, der angibt, ob die Rolle einen expliziten Titel hat oder nicht.

target: str

Das Linkziel für den interpretierten Text.

title: str

Der Linktitel für den interpretierten Text.

class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)[Quelle]

Eine Basisklasse für Bildkonverter.

Ein Bildkonverter ist eine Art Docutils-Transformationsmodul. Er wird verwendet, um Bilddateien, die von einem Builder nicht unterstützt werden, in das für diesen Builder geeignete Format zu konvertieren.

Zum Beispiel unterstützt der LaTeX Builder PDF-, PNG- und JPEG-Formate als Bilder. SVG-Bilder werden jedoch nicht unterstützt. In solchen Fällen ermöglichen Bildkonverter das Einbetten dieser nicht unterstützten Bilder in das Dokument. Einer der Bildkonverter; sphinx.ext.imgconverter kann ein SVG-Bild unter Verwendung von Imagemagick intern in das PNG-Format konvertieren.

Es gibt drei Schritte, um Ihren benutzerdefinierten Bildkonverter zu erstellen

  1. Erstellen Sie eine Unterklasse der Klasse ImageConverter

  2. Überschreiben Sie conversion_rules, is_available() und convert()

  3. Registrieren Sie Ihren Bildkonverter bei Sphinx mit Sphinx.add_post_transform()

convert(_from: str | PathLike[str], _to: str | PathLike[str]) → bool[Quelle]

Eine Bilddatei in das erwartete Format konvertieren.

_from ist ein Pfad zur Quelldatei des Bildes und _to ist ein Pfad zur Zieldatei.

is_available() → bool[source]

Gibt zurück, ob der Bildkonverter verfügbar ist oder nicht.

available: bool | None = None

Der Konverter ist verfügbar oder nicht. Wird beim ersten Aufruf des Builds gefüllt. Das Ergebnis wird im selben Prozess geteilt.

conversion_rules: list[tuple[str, str]] = []

Eine Konvertierungsregel, die der Bildkonverter unterstützt. Sie wird als Liste von Paaren aus Quellbildformat (MIME-Typ) und Zielformat dargestellt.

conversion_rules = [
    ('image/svg+xml', 'image/png'),
    ('image/gif', 'image/png'),
    ('application/pdf', 'image/png'),
]
default_priority = 200

Numerische Priorität dieser Transformation, 0 bis 999 (Überschreibung).

Dienstfunktionen

sphinx.util.parsing.nested_parse_to_nodes(state: RSTState, text: str | StringList, *, source: str = '<generated text>', offset: int = 0, allow_section_headings: bool = True, keep_title_context: bool = False) → list[Node][source]

text in Knoten parsen.

Parameter:

  • state – Der Zustand der Zustandsmaschine. Muss eine Unterklasse von RSTState sein.

  • text – Text in Zeichenkettenform. StringList wird ebenfalls akzeptiert.

  • source – Die Quelle des Textes, die beim Erstellen einer neuen StringList verwendet wird.

  • offset – Der Offset des Inhalts.

  • allow_section_headings – Sind Titel (Abschnitte) in text erlaubt? Beachten Sie, dass diese Option die üblichen Prüfungen von Docutils auf die Doctree-Struktur umgeht und eine falsche Verwendung dieser Option zu einem inkohärenten Doctree führen kann. In Docutils sollten Abschnittsknoten nur Kinder von document oder section Knoten sein.

  • keep_title_context –

    Wenn dies False ist (Standard), dann wird content so analysiert, als wäre es ein unabhängiges Dokument, was bedeutet, dass Titeldekorationen (z. B. Unterstreichungen) nicht mit dem umgebenden Dokument übereinstimmen müssen. Dies ist nützlich, wenn der analysierte Inhalt aus einem völlig anderen Kontext stammt, z. B. aus Docstrings. Wenn dies True ist, müssen Titelunterstreichungen mit denen im umgebenden Dokument übereinstimmen, andernfalls ist das Verhalten undefiniert.

    Warnung: Bis Docutils 0.21 werden Abschnitte mit einem Dekorationsstil, der einem Level entspricht, der höher ist als das aktuelle Abschnittslevel, stillschweigend verworfen! Seit Docutils 0.22.1 wird ein Fehler gemeldet.

Hinzugefügt in Version 7.4.

Diensttypen

class sphinx.util.typing.ExtensionMetadata[source]

Die Metadaten, die von der setup()-Funktion einer Erweiterung zurückgegeben werden.

Siehe Extension metadata.

env_version: int

Eine Ganzzahl, die die Version der von der Erweiterung hinzugefügten Umgebungsdaten identifiziert.

parallel_read_safe: bool

Gibt an, ob das parallele Lesen von Quelldateien von der Erweiterung unterstützt wird.

parallel_write_safe: bool

Gibt an, ob das parallele Schreiben von Ausgabedateien von der Erweiterung unterstützt wird (Standard: True).

version: str

Die Erweiterungsversion (Standard: 'unknown version').