Builder API

class sphinx.builders.Builder

Dies ist die Basisklasse für alle Builder.

Sie folgt diesem grundlegenden Workflow

Aufrufgraph für den Standard-Sphinx-Build-Workflow

Überschreibbare Attribute

Diese Klassenattribute sollten in Builder-Unterklassen gesetzt werden

name: ClassVar[str] = ''

Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format: ClassVar[str] = ''

Das Ausgabeformat des Builders oder '' wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateierweiterung, z.B. "html", obwohl jeder Stringwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Erweiterungen verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

epilog: ClassVar[str] = ''

Die Nachricht, die beim erfolgreichen Abschluss des Builds ausgegeben wird. Dies kann eine printf-ähnliche Vorlagenzeichenkette mit den folgenden Schlüsseln sein: outdir, project

allow_parallel: ClassVar[bool] = False

Ob es sicher ist, parallele Aufrufe von write_doc() durchzuführen.

supported_image_types: ClassVar[list[str]] = []

Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

supported_remote_images: ClassVar[bool] = False

Der Builder kann Ausgabedokumente erstellen, die beim Öffnen externe Bilder abrufen können.

supported_data_uri_images: ClassVar[bool] = False

Das vom Builder erzeugte Dateiformat erlaubt es, Bilder mittels data-URIs einzubetten.

default_translator_class: ClassVar[type[nodes.NodeVisitor]]

Standard-Übersetzerklasse für den Builder. Dies kann durch set_translator() überschrieben werden.

Kernmethoden

Diese Methoden definieren den Kern-Build-Workflow und dürfen nicht überschrieben werden

final build_all() → None

Baut alle Quelldateien.

final build_specific(filenames: Sequence[Path]) → None

Baut nur so viel wie nötig für Änderungen in den filenames neu.

final build_update() → None

Baut nur das neu, was seit dem letzten Build geändert oder hinzugefügt wurde.

final build(docnames: Iterable[str] | None, summary: str | None = None, method: Literal['all', 'specific', 'update'] = 'update') → None

Haupt-Build-Methode, normalerweise aufgerufen von einer spezifischen build_*-Methode.

Aktualisiert zuerst die Umgebung und ruft dann write() auf.

final read() → list[str]

Liest alle Dateien neu oder geändert seit dem letzten Update neu ein.

Speichert alle Umgebungs-Docnames im kanonischen Format (d.h. unter Verwendung von SEP als Trennzeichen anstelle von os.path.sep).

final read_doc(docname: str, *, _cache: bool = True) → None

Analysiert eine Datei und fügt/aktualisiert Inventareinträge für den Doctree.

final write_doctree(docname: str, doctree: document, *, _cache: bool = True) → None

Schreibt den Doctree in eine Datei, die als Cache für Neubildungen verwendet wird.

final write(build_docnames: Iterable[str] | None, updated_docnames: Iterable[str], method: Literal['all', 'specific', 'update'] = 'update') → None

Schreibt die Builder-spezifischen Ausgabedateien.

Abstrakte Methoden

Diese müssen in Builder-Unterklassen implementiert werden

get_outdated_docs() → str | Iterable[str]

Gibt eine Iterierbare Liste von Ausgabedateien zurück, die veraltet sind, oder eine Zeichenkette, die beschreibt, was ein Update-Build erstellen wird.

Wenn der Builder keine einzelnen Dateien erstellt, die Quellendateien entsprechen, geben Sie hier eine Zeichenkette zurück. Wenn er dies tut, geben Sie eine Iterierbare Liste der Dateien zurück, die geschrieben werden müssen.

write_doc(docname: str, doctree: document) → None

Schreibt die Ausgabedatei für das Dokument

Parameter:

• docname – der docname.

• doctree – definiert den zu schreibenden Inhalt.

Der Ausgabedateiname muss innerhalb dieser Methode ermittelt werden, typischerweise durch Aufruf von get_target_uri() oder get_relative_uri().

get_target_uri(docname: str, typ: str | None = None) → str

Gibt die Ziel-URI für einen Dokumentennamen zurück.

typ kann verwendet werden, um die Link-Charakteristik für einzelne Builder zu qualifizieren.

Überschreibbare Methoden

Diese Methoden können in Builder-Unterklassen überschrieben werden

init() → None

Lädt notwendige Vorlagen und führt die Initialisierung durch. Die Standardimplementierung tut nichts.

write_documents(docnames: Set[str]) → None

Schreibt alle Dokumente in docnames.

Diese Methode kann überschrieben werden, wenn ein Builder keine Ausgabedateien für jedes Dokument erstellt.

prepare_writing(docnames: Set[str]) → None

Ein Ort, an dem Sie Logik hinzufügen können, bevor write_doc() ausgeführt wird

copy_assets() → None

Wo Assets (Bilder, statische Dateien usw.) vor dem Schreiben kopiert werden

get_relative_uri(from_: str, to: str, typ: str | None = None) → str

Gibt eine relative URI zwischen zwei Quellendateien zurück.

Wirft:

NoUri, wenn es keinen sinnvollen URI zurückgeben kann.

finish() → None

Schließt den Build-Prozess ab.

Die Standardimplementierung tut nichts.

Attribute

Attribute, die von der Builder-Instanz aufgerufen werden können

events

Ein EventManager-Objekt.

Überschreibbare Attribute (Erweiterungen)

Builder-Unterklassen können diese Attribute setzen, um integrierte Erweiterungen zu unterstützen

supported_linkcode: str

Standardmäßig fügt die linkcode-Erweiterung nur Referenzen für einen html-Builder ein. Das Klassenattribut supported_linkcode kann in einem nicht-HTML-Builder definiert werden, um die Verwaltung von von linkcode generierten Referenzen zu unterstützen. Der erwartete Wert für dieses Attribut ist ein Ausdruck, der mit der only-Direktive kompatibel ist.

Zum Beispiel, wenn ein Builder custom-builder hieß, kann Folgendes verwendet werden

class CustomBuilder(Builder):
    supported_linkcode = 'custom-builder'
    ...

Vorheriger

Build-Umgebungs-API

Nächster

Event Manager API