Event callbacks API

Das Verbinden von Callback-Funktionen mit Ereignissen ist eine einfache Möglichkeit, Sphinx zu erweitern, indem der Build-Prozess an verschiedenen Punkten eingehakt wird.

Verwenden Sie Sphinx.connect() in der setup-Funktion einer Erweiterung oder einer setup-Funktion in der conf.py Ihres Projekts, um Funktionen mit den Ereignissen zu verbinden.

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)

Siehe auch

Erweiterungen können ihre eigenen Ereignisse hinzufügen, indem sie Sphinx.add_event() verwenden und diese mit EventManager.emit() oder EventManager.emit_firstresult() aufrufen.

Übersicht über Kernereignisse

Nachfolgend finden Sie eine Übersicht über die Kernereignisse, die während eines Builds auftreten.

1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)

for docname in docnames:
   5. event.env-purge-doc(app, env, docname)

   if doc changed and not removed:
      6. source-read(app, docname, source)
      7. run source parsers: text -> docutils.document
         - parsers can be added with the app.add_source_parser() API
         - event.include-read(app, relative_path, parent_docname, content)
           is called for each include directive
      8. apply transforms based on priority: docutils.document -> docutils.document
         - event.doctree-read(app, doctree) is called in the middle of transforms,
           transforms come before/after this event depending on their priority.

9. event.env-merge-info(app, env, docnames, other)
   - if running in parallel mode, this event will be emitted for each process

10. event.env-updated(app, env)
11. event.env-get-updated(app, env)

if environment is written to disk:
   12. event.env-check-consistency(app, env)

13. event.write-started(app, builder)
    - This is called after ``app.parallel_ok`` has been set,
      which must not be altered by any event handler.

# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
# For builders that output a single page, they are first joined into a single doctree before post-transforms
# or the doctree-resolved event is emitted
for docname in updated-docs:
   14. apply post-transforms (by priority): docutils.document -> docutils.document
   15. event.doctree-resolved(app, doctree, docname)
       - In the event that any reference nodes fail to resolve, the following may emit:
       - event.missing-reference(app, env, node, contnode)
       - event.warn-missing-reference(app, domain, node)

16. Generate output files
17. event.build-finished(app, exception)

Hier ist auch ein Flussdiagramm der Ereignisse im Kontext des Sphinx-Build-Prozesses

Flussdiagramm der Sphinx-Kernereignisse

Details zu Kernereignissen

Hier ist eine detailliertere Liste dieser Ereignisse.

config-inited(app, config)

Parameter:

• app – Sphinx

• config – Config

Wird ausgelöst, wenn das Konfigurationsobjekt initialisiert wurde.

Hinzugefügt in Version 1.8.

builder-inited(app)

Parameter:

app – Sphinx

Wird ausgelöst, wenn das Builder-Objekt erstellt wurde (verfügbar als app.builder).

env-get-outdated(app, env, added, changed, removed)

Parameter:

• app – Sphinx

• env – BuildEnvironment

• added – Set[str]

• changed – Set[str]

• removed – Set[str]

Gibt zurück:

Sequence[str] zusätzlicher Docnames, die neu gelesen werden sollen

Wird ausgelöst, wenn die Umgebung bestimmt, welche Quelldateien sich geändert haben und neu gelesen werden müssen. added, changed und removed sind Mengen von Docnames, die von der Umgebung ermittelt wurden. Sie können eine Liste von Docnames zurückgeben, die zusätzlich zu diesen neu gelesen werden sollen.

Hinzugefügt in Version 1.1.

env-purge-doc(app, env, docname)

Parameter:

• app – Sphinx

• env – BuildEnvironment

• docname – str

Wird ausgelöst, wenn alle Spuren einer Quelldatei aus der Umgebung gelöscht werden sollen, d. h. wenn die Quelldatei entfernt wird oder bevor sie frisch gelesen wird. Dies ist für Erweiterungen, die ihre eigenen Caches in Attributen der Umgebung speichern.

Zum Beispiel gibt es einen Cache aller Module in der Umgebung. Wenn eine Quelldatei geändert wurde, werden die Cache-Einträge für die Datei gelöscht, da die Moduldeklarationen aus der Datei entfernt worden sein könnten.

Hinzugefügt in Version 0.5.

env-before-read-docs(app, env, docnames)

Parameter:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

Wird ausgelöst, nachdem die Umgebung die Liste aller hinzugefügten und geänderten Dateien bestimmt hat und kurz bevor sie diese liest. Sie ermöglicht es Erweiterungsautoren, die Liste der Docnames (inplace) vor der Verarbeitung neu anzuordnen oder weitere Docnames hinzuzufügen, die Sphinx nicht als geändert betrachtet hat (aber niemals Docnames hinzufügen, die nicht in found_docs enthalten sind).

Sie können auch Dokumentnamen entfernen; tun Sie dies mit Vorsicht, da Sphinx geänderte Dateien als unverändert behandelt.

Hinzugefügt in Version 1.3.

source-read(app, docname, content)

Parameter:

• app – Sphinx

• docname – str

• content – list[str] mit einem einzelnen Element, das den Inhalt der inkludierten Datei darstellt.

Wird ausgelöst, wenn eine Quelldatei gelesen wurde.

Sie können den content verarbeiten und dieses Element ersetzen, um Transformationen auf Quellcode-Ebene zu implementieren.

Wenn Sie beispielsweise $-Zeichen zur Abgrenzung von Inline-Mathematik verwenden möchten, wie in LaTeX, können Sie einen regulären Ausdruck verwenden, um $...$ durch :math:`...` zu ersetzen.

Hinzugefügt in Version 0.5.

include-read(app, relative_path, parent_docname, content)

Parameter:

• app – Sphinx

• relative_path – Path, die die inkludierte Datei relativ zum Source Directory darstellt.

• parent_docname – str des Dokumentnamens, der die include-Direktive enthält.

• content – list[str] mit einem einzelnen Element, das den Inhalt der inkludierten Datei darstellt.

Wird ausgelöst, wenn eine Datei mit der include-Direktive gelesen wurde.

Sie können den content verarbeiten und dieses Element ersetzen, um den inkludierten Inhalt zu transformieren, wie beim source-read-Ereignis.

Hinzugefügt in Version 7.2.5.

Siehe auch

Die include-Direktive und das source-read-Ereignis.

object-description-transform(app, domain, objtype, contentnode)

Parameter:

• app – Sphinx

• domain – str

• objtype – str

• contentnode – desc_content

Wird ausgelöst, wenn eine Objektbeschreibung-Direktive ausgeführt wurde. Die Argumente domain und objtype sind Strings, die die Objektbeschreibung des Objekts angeben. Und contentnode ist ein Inhalt für das Objekt. Es kann inplace modifiziert werden.

Hinzugefügt in Version 2.4.

doctree-read(app, doctree)

Parameter:

• app – Sphinx

• doctree – docutils.nodes.document

Wird ausgelöst, wenn ein Doctree von der Umgebung analysiert und gelesen wurde und kurz davor ist, gepickelt zu werden. Der doctree kann inplace modifiziert werden.

missing-reference(app, env, node, contnode)

Parameter:

• app – Sphinx

• env – BuildEnvironment

• node – Der zu lösende pending_xref-Knoten. Seine Attribute reftype, reftarget, modname und classname bestimmen den Typ und das Ziel der Referenz.

• contnode – Der Knoten, der den Text und die Formatierung innerhalb der zukünftigen Referenz trägt und ein Kind des zurückgegebenen Referenzknotens sein sollte.

Gibt zurück:

Ein neuer Knoten, der anstelle des Knotens in den Dokumentbaum eingefügt werden soll, oder None, damit andere Handler es versuchen können.

Wird ausgelöst, wenn eine Querverbindung zu einem Objekt nicht aufgelöst werden kann. Wenn der Ereignishandler die Referenz auflösen kann, sollte er einen neuen docutils-Knoten zurückgeben, der anstelle des Knotens node in den Dokumentbaum eingefügt wird. Normalerweise ist dies ein reference-Knoten, der contnode als Kind enthält. Wenn der Handler die Querverbindung nicht auflösen kann, kann er entweder None zurückgeben, damit andere Handler es versuchen können, oder NoUri auslösen, um zu verhindern, dass andere Handler es versuchen, und eine Warnung unterdrücken, dass diese Querverbindung nicht aufgelöst wurde.

Hinzugefügt in Version 0.5.

warn-missing-reference(app, domain, node)

Parameter:

• app – Sphinx

• domain – Die Domain der fehlenden Referenz.

• node – Der pending_xref-Knoten, der nicht aufgelöst werden konnte.

Gibt zurück:

True, wenn eine Warnung ausgegeben wurde, andernfalls None

Wird ausgelöst, wenn eine Querverbindung zu einem Objekt auch nach missing-reference nicht aufgelöst werden kann. Wenn der Ereignishandler Warnungen für die fehlende Referenz ausgeben kann, sollte er True zurückgeben. Die Konfigurationsvariablen nitpick_ignore und nitpick_ignore_regex verhindern, dass das Ereignis für die entsprechenden Knoten ausgelöst wird.

Hinzugefügt in Version 3.4.

doctree-resolved(app, doctree, docname)

Parameter:

• app – Sphinx

• doctree – docutils.nodes.document

• docname – str

Wird ausgelöst, wenn ein Doctree von der Umgebung "aufgelöst" wurde, d. h. alle Referenzen aufgelöst und TOCs eingefügt wurden. Der doctree kann inplace modifiziert werden.

Hier ist der Ort, um benutzerdefinierte Knoten zu ersetzen, die keine Besucher-Methoden in den Writern haben, damit sie keine Fehler verursachen, wenn die Writer sie antreffen.

env-merge-info(app, env, docnames, other)

Parameter:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

• other – BuildEnvironment

Dieses Ereignis wird nur ausgelöst, wenn paralleles Lesen von Dokumenten aktiviert ist. Es wird einmal für jeden Unterprozess ausgelöst, der einige Dokumente gelesen hat.

Sie müssen dieses Ereignis in einer Erweiterung behandeln, die Daten unter einem benutzerdefinierten Speicherort in der Umgebung speichert. Andernfalls wird die Umgebung im Hauptprozess die im Unterprozess gespeicherten Informationen nicht kennen.

other ist das Umgebungsobjekt aus dem Unterprozess, env ist die Umgebung aus dem Hauptprozess. docnames ist eine Menge von Dokumentnamen, die im Unterprozess gelesen wurden.

Hinzugefügt in Version 1.3.

env-updated(app, env)

Parameter:

• app – Sphinx

• env – BuildEnvironment

Gibt zurück:

Iterable von str

Wird ausgelöst, nachdem alle Dokumente gelesen wurden und die Umgebung sowie alle Doctrees nun auf dem neuesten Stand sind.

Sie können ein Iterable von Docnames aus dem Handler zurückgeben. Diese Dokumente werden dann als aktualisiert betrachtet und während der Schreibphase (neu) geschrieben.

Hinzugefügt in Version 0.5.

Geändert in Version 1.3: Der Rückgabewert von Handlern wird nun verwendet.

env-get-updated(app, env)

Parameter:

• app – Sphinx

• env – BuildEnvironment

Gibt zurück:

Iterable von str

Wird ausgelöst, wenn die Umgebung bestimmt, welche Quelldateien sich geändert haben und neu gelesen werden sollen. Sie können ein Iterable von Docnames zurückgeben, die neu gelesen werden sollen.

env-check-consistency(app, env)

Parameter:

• app – Sphinx

• env – BuildEnvironment

Wird während der Konsistenzprüfungsphase ausgelöst. Sie können die Konsistenz von Metadaten für alle Dokumente prüfen.

Hinzugefügt in Version 1.6.

write-started(app, builder)

Parameter:

• app – Sphinx

• builder – Builder

Wird ausgelöst, bevor der Builder beginnt, Dokumente aufzulösen und zu schreiben.

Hinzugefügt in Version 7.4.

build-finished(app, exception)

Parameter:

• app – Sphinx

• exception – Exception oder None

Wird ausgelöst, wenn ein Build beendet ist, bevor Sphinx beendet wird, normalerweise für Bereinigungsarbeiten. Dieses Ereignis wird auch dann ausgelöst, wenn der Build-Prozess eine Ausnahme ausgelöst hat, die als Argument exception übergeben wird. Die Ausnahme wird nach der Ausführung der Ereignishandler in der Anwendung erneut ausgelöst. Wenn der Build-Prozess keine Ausnahme ausgelöst hat, ist exception None. Dies ermöglicht die Anpassung von Bereinigungsaktionen je nach Ausnahmezustand.

Hinzugefügt in Version 0.5.

Builder-spezifische Ereignisse

Diese Ereignisse werden von spezifischen Buildern ausgelöst.

html-collect-pages(app)

Parameter:

app – Sphinx

Gibt zurück:

Iterable von (pagename, context, templatename), wobei pagename und templatename Strings sind und context ein dict[str, Any] ist.

Wird ausgelöst, wenn der HTML-Builder beginnt, Nicht-Dokumenten-Seiten zu schreiben.

Sie können Seiten zum Schreiben hinzufügen, indem Sie ein Iterable von diesem Ereignis zurückgeben.

Hinzugefügt in Version 1.0.

html-page-context(app, pagename, templatename, context, doctree)

Parameter:

• app – Sphinx

• pagename – str

• templatename – str

• context – dict[str, Any]

• doctree – docutils.nodes.document oder None

Gibt zurück:

str oder None

Wird ausgelöst, wenn der HTML-Builder ein Kontext-Dictionary zum Rendern einer Vorlage erstellt hat – dies kann verwendet werden, um dem Kontext benutzerdefinierte Elemente hinzuzufügen.

Das Argument pagename ist der kanonische Name der gerenderten Seite, d. h. ohne das Suffix .html und mit Schrägstrichen als Pfadtrenner. Der templatename ist der Name der zu rendernden Vorlage, dies wird 'page.html' für alle Seiten aus reStructuredText-Dokumenten sein.

Das Argument context ist ein Dictionary von Werten, die der Template-Engine zum Rendern der Seite übergeben werden und das modifiziert werden kann, um benutzerdefinierte Werte einzuschließen.

Das Argument doctree ist ein Doctree, wenn die Seite aus einem reStructuredText-Dokument erstellt wird; es ist None, wenn die Seite nur aus einer HTML-Vorlage erstellt wird.

Sie können einen String aus dem Handler zurückgeben, dieser ersetzt dann 'page.html' als HTML-Vorlage für diese Seite.

Tipp

Sie können JS/CSS-Dateien für die spezifische Seite über Sphinx.add_js_file() und Sphinx.add_css_file() (seit v3.5.0) installieren.

Hinzugefügt in Version 0.4.

Geändert in Version 1.3: Der Rückgabewert kann nun einen Vorlagennamen angeben.

linkcheck-process-uri(app, uri)

Parameter:

• app – Sphinx

• uri – str der gesammelten URI

Gibt zurück:

str oder None

Wird ausgelöst, wenn der Linkcheck-Builder Hyperlinks aus Dokumenten sammelt.

Die Ereignishandler können die URI ändern, indem sie einen String zurückgeben.

Hinzugefügt in Version 4.1.

Vorherige

Application API

Nächste

Project API