Sphinx API¶
Da viele Projekte spezielle Funktionen in ihrer Dokumentation benötigen, ist Sphinx darauf ausgelegt, auf mehreren Ebenen erweiterbar zu sein.
Hier sind einige Dinge, die Sie in einer Erweiterung tun können:
Fügen Sie neue Builder hinzu, um neue Ausgabeformate oder Aktionen für die analysierten Dokumente zu unterstützen.
Registrieren Sie benutzerdefinierte reStructuredText-Rollen und Direktiven, um die Auszeichnung mithilfe der Docutils Markup API zu erweitern.
Fügen Sie benutzerdefinierten Code an sogenannten "Hook-Punkten" an strategischen Stellen im Build-Prozess hinzu. Dies ermöglicht es Ihnen, einen Hook zu registrieren und spezialisierten Code auszuführen. Sehen Sie sich zum Beispiel die Event Callbacks API an.
Eine Erweiterung ist einfach ein Python-Modul mit einer setup()-Funktion. Ein Benutzer aktiviert die Erweiterung, indem er den Modulnamen der Erweiterung (oder ein Untermodul) in seinen extensions-Konfigurationswert einträgt.
Wenn sphinx-build ausgeführt wird, versucht Sphinx, jedes aufgeführte Modul zu importieren und ihrmodul.setup(app) auszuführen. Diese Funktion wird verwendet, um die Erweiterung vorzubereiten (z. B. durch Ausführen von Python-Code), Ressourcen zu verknüpfen, die Sphinx im Build-Prozess verwendet (wie CSS- oder HTML-Dateien), und Sphinx über alles zu informieren, was die Erweiterung bietet (wie Direktiven- oder Rollendefinitionen). Das app-Argument ist eine Instanz von Sphinx und gibt Ihnen die Kontrolle über die meisten Aspekte des Sphinx-Builds.
Hinweis
Die Konfigurationsdatei selbst kann als Erweiterung behandelt werden, wenn sie eine setup()-Funktion enthält. Alle anderen zu ladenden Erweiterungen müssen im extensions-Konfigurationswert aufgeführt sein.
Der Rest dieser Seite beschreibt einige übergeordnete Aspekte der Entwicklung von Erweiterungen und verschiedene Teile des Sphinx-Verhaltens, die Sie steuern können. Einige Beispiele, wie Erweiterungen erstellt und verwendet werden können, um verschiedene Teile von Sphinx zu steuern, finden Sie in den Tutorials.
Wichtige Objekte¶
Beim Schreiben einer Erweiterung werden Sie die API mehrerer Schlüsselobjekte verwenden. Dies sind:
- Anwendung
Das Anwendungsobjekt (normalerweise
appgenannt) ist eine Instanz vonSphinx. Es steuert die meisten übergeordneten Funktionen, wie das Laden von Konfigurationen, die Initialisierung der Umgebung und die Einrichtung von Erweiterungen.- Umgebung
Das Build-Umgebungsobjekt (normalerweise
envgenannt) ist eine Instanz vonBuildEnvironment. Es ist für das Parsen der Quelldokumente zuständig, speichert alle Metadaten über die Dokumentensammlung und wird nach jedem Build auf die Festplatte serialisiert.Seine API bietet Methoden zum Zugriff auf Metadaten, zum Auflösen von Referenzen usw. Es kann auch von Erweiterungen verwendet werden, um Informationen zu cachen, die für inkrementelle Neuerstellungen erhalten bleiben sollen.
Wenn Sie das Anwendungs- oder Builder-Objekt haben, ist die Umgebung als
app.envoderbuilder.envverfügbar. InSphinxDirective,SphinxRoleoderSphinxTransform-Unterklassen ist die Umgebung alsself.envverfügbar.- Builder
Das Builder-Objekt (normalerweise
buildergenannt) ist eine Instanz einer bestimmten Unterklasse vonBuilder. Jede Builder-Klasse weiß, wie die analysierten Dokumente in ein Ausgabeformat konvertiert oder anderweitig verarbeitet werden (z. B. externe Links überprüfen).Wenn Sie das Anwendungs-Objekt haben, ist der Builder als
app.builderverfügbar.- Konfiguration
Das Konfigurationsobjekt (normalerweise
configgenannt) stellt die Werte der inconf.pygesetzten Konfigurationswerte als Attribute bereit. Es ist eine Instanz vonConfig.Die Konfiguration ist als
env.config,builder.configoderapp.configverfügbar. InSphinxDirective,SphinxRoleoderSphinxTransform-Unterklassen ist die Umgebung alsself.configverfügbar.- Events
Das Event-Manager-Objekt (normalerweise
eventsgenannt) verwaltet und verteilt das Event-System von Sphinx. Es ist eine Instanz vonEventManager.Der Event-Manager ist als
env.events,builder.eventsoderapp.eventsverfügbar.
Ein Beispiel für die Verwendung dieser Objekte finden Sie in den Tutorials.
Build-Phasen¶
Um die Erweiterungsmechanismen zu verstehen, ist es wichtig zu wissen, wie ein Sphinx-Projekt erstellt wird: Dies geschieht in mehreren Phasen.
![digraph phases {
graph [
rankdir = LR
]
node [
shape = rect;
style = filled;
fillcolor ="#f7f7f7";
fontcolor = "#0a507a"
]
Initialization -> Reading;
Reading -> "Consistency checks";
"Consistency checks" -> Resolving;
Resolving -> Writing;
}](../_images/graphviz-339e3ad43e173f7c950f79bf4d41f82f906d2175.png)
Build-Phasen¶
Phase 0: Initialisierung
In dieser Phase passiert fast nichts von Interesse für uns. Das Quellverzeichnis wird nach Quelldateien durchsucht und Erweiterungen werden initialisiert. Wenn eine gespeicherte Build-Umgebung existiert, wird diese geladen, andernfalls wird eine neue erstellt.
Phase 1: Lesen
In Phase 1 werden alle Quelldateien (und bei nachfolgenden Builds diejenigen, die neu oder geändert sind) gelesen und analysiert. Dies ist die Phase, in der Direktiven und Rollen von Docutils angetroffen und der entsprechende Code ausgeführt wird. Das Ergebnis dieser Phase ist für jede Quelldatei ein *Doctree*; das ist ein Baum von Docutils-Knoten. Für Dokumentenelemente, die erst bekannt sind, wenn alle vorhandenen Dateien gelesen wurden, werden temporäre Knoten erstellt.
Es gibt von Docutils bereitgestellte Knoten, die in der Docutils-Dokumentation dokumentiert sind. Zusätzliche Knoten werden von Sphinx und hier dokumentiert.
Während des Lesens wird die Build-Umgebung mit allen Meta- und Cross-Reference-Daten der gelesenen Dokumente aktualisiert, wie z. B. Labels, Überschriftennamen, beschriebene Python-Objekte und Indexeinträge. Diese werden später verwendet, um die temporären Knoten zu ersetzen.
Die analysierten Doctrees werden auf der Festplatte gespeichert, da es nicht möglich ist, sie alle im Speicher zu halten.
Phase 2: Konsistenzprüfungen
Es werden einige Prüfungen durchgeführt, um sicherzustellen, dass es keine Überraschungen in den erstellten Dokumenten gibt.
Phase 3: Auflösen
Nachdem nun die Metadaten und Cross-Reference-Daten aller vorhandenen Dokumente bekannt sind, werden alle temporären Knoten durch Knoten ersetzt, die mit Hilfe von Komponenten namens Transforms in Ausgabe umgewandelt werden können. Zum Beispiel werden Links für vorhandene Objektverweise erstellt, und für nicht vorhandene werden einfache Literal-Knoten erstellt.
Phase 4: Schreiben
Diese Phase konvertiert die aufgelösten Doctrees in das gewünschte Ausgabeformat, z. B. HTML oder LaTeX. Dies geschieht über einen sogenannten Docutils Writer, der die einzelnen Knoten jedes Doctrees besucht und dabei eine Ausgabe erzeugt.
Hinweis
Einige Builder weichen von diesem allgemeinen Build-Plan ab. Zum Beispiel benötigt der Builder, der externe Links überprüft, nichts weiter als die analysierten Doctrees und hat daher keine Phasen 2-4.
Ein Anwendungsbeispiel finden Sie unter Erweitern des Build-Prozesses.
Erweiterungsmetadaten¶
Hinzugefügt in Version 1.3.
Die Funktion setup() sollte ein Dictionary zurückgeben. Dies wird von Sphinx als Metadaten der Erweiterung behandelt. Derzeit erkannte Metadaten-Schlüssel sind:
'version'Eine Zeichenkette, die die Version der Erweiterung identifiziert. Sie wird zur Überprüfung von Erweiterungsversionsanforderungen (siehe
needs_extensions) und zu Informationszwecken verwendet. Wenn keine Versionszeichenkette zurückgegeben wird, wird standardmäßig'unknown version'verwendet.'env_version'Eine positive Ganzzahl größer als Null, die die Version der von der Erweiterung in der Umgebung gespeicherten Daten aufzeichnet.
Aufmerksamkeit
Wenn
'env_version'nicht gesetzt ist, darf die Erweiterung keine Daten oder Zustände direkt im Umgebungsobjekt (env) speichern.Dieser Schlüssel muss definiert werden, wenn die Erweiterung das
env-Objekt zum Speichern von Daten verwendet. Die Versionsnummer muss inkrementiert werden, wann immer sich der Typ, die Struktur oder die Bedeutung der gespeicherten Daten ändern, um sicherzustellen, dass Sphinx keine ungültigen Daten aus einer gecachten Umgebung zu laden versucht.Hinzugefügt in Version 1.8.
'parallel_read_safe'Ein boolescher Wert, der angibt, ob die parallele Lesung von Quelldateien verwendet werden kann, wenn die Erweiterung geladen ist. Standardmäßig ist dies
False, was bedeutet, dass Sie Ihre Erweiterung explizit als sicher für die parallele Lesung kennzeichnen müssen, nachdem Sie dies überprüft haben.Wichtig
Wenn *parallel-read-safe* auf
Truegesetzt ist, muss die Erweiterung die folgenden Bedingungen erfüllen:Die Kernlogik der Erweiterung ist während der Lesephase parallel ausführbar.
Sie hat Event-Handler für die Events
env-merge-infoundenv-purge-doc, wenn sie während der Lesephase Daten im Build-Umgebungsobjekt (env) speichert.
'parallel_write_safe'Ein boolescher Wert, der angibt, ob das parallele Schreiben von Ausgabedateien verwendet werden kann, wenn die Erweiterung geladen ist. Da Erweiterungen den Prozess normalerweise nicht negativ beeinflussen, ist dies standardmäßig auf
Truegesetzt.Wichtig
Wenn *parallel-write-safe* auf
Truegesetzt ist, muss die Erweiterung die folgenden Bedingungen erfüllen:Die Kernlogik der Erweiterung ist während der Schreibphase parallel ausführbar.
APIs zum Erstellen von Erweiterungen¶
Diese Abschnitte bieten eine vollständigere Beschreibung der Werkzeuge, die Ihnen bei der Entwicklung von Sphinx-Erweiterungen zur Verfügung stehen. Einige sind Kernbestandteil von Sphinx (wie die Application API), während andere spezifisches Verhalten auslösen (wie die i18n API).