Builder (Builders)¶

Dies sind die integrierten Sphinx-Builder. Weitere Builder können durch Extensions hinzugefügt werden.

Der „Name“ des Builders muss den Kommandozeilenoptionen -M oder -b von sphinx-build übergeben werden, um einen Builder auszuwählen.

Die gebräuchlichsten Builder sind

html: Erstellt HTML-Seiten. Dies ist der Standard-Builder.
dirhtml: Erstellt HTML-Seiten, aber mit einem separaten Verzeichnis pro Dokument. Sorgt für schönere URLs (ohne .html), wenn sie von einem Webserver ausgeliefert werden.
singlehtml: Erstellt eine einzelne HTML-Datei mit dem gesamten Inhalt.
htmlhelp, qthelp, devhelp, epub: Erstellt HTML-Dateien mit zusätzlichen Informationen für die Erstellung einer Dokumentationssammlung in einem dieser Formate.
applehelp: Erstellt ein Apple Help Book. Benötigt hiutil und codesign, die nicht Open Source sind und derzeit nur auf Mac OS X 10.6 und höher verfügbar sind.
latex: Erstellt LaTeX-Quellen, die mit pdflatex zu einem PDF-Dokument kompiliert werden können.
man: Erstellt Manual Pages im groff-Format für UNIX-Systeme.
texinfo: Erstellt Texinfo-Dateien, die mit makeinfo zu Info-Dateien verarbeitet werden können.
text: Erstellt reine Textdateien.
gettext: Erstellt gettext-artige Kataloge von Meldungen (.pot-Dateien).
doctest: Führt alle Doctests in der Dokumentation aus, wenn die doctest-Extension aktiviert ist.
linkcheck: Überprüft die Integrität aller externen Links.
xml: Erstellt Docutils-native XML-Dateien.
pseudoxml: Erstellt kompakte, hübsch formatierte „Pseudo-XML“-Dateien, die die interne Struktur der Zwischen-Dokumenten-Bäume anzeigen.

class sphinx.builders.html.StandaloneHTMLBuilder[source]¶

Dies ist der Standard-HTML-Builder. Seine Ausgabe ist ein Verzeichnis mit HTML-Dateien, komplett mit Stilvorlagen und optional den reStructuredText-Quellen. Es gibt ziemlich viele Konfigurationswerte, die die Ausgabe dieses Builders anpassen. Details finden Sie im Kapitel Optionen für HTML-Ausgabe.

name = 'html'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

class sphinx.builders.dirhtml.DirectoryHTMLBuilder[source]¶

Dies ist eine Unterklasse des Standard-HTML-Builders. Seine Ausgabe ist ein Verzeichnis mit HTML-Dateien, wobei jede Datei index.html heißt und in einem Unterverzeichnis platziert wird, das wie sein Seitenname benannt ist. Zum Beispiel wird das Dokument markup/rest.rst nicht zu einer Ausgabedatei markup/rest.html führen, sondern zu markup/rest/index.html. Beim Generieren von Links zwischen Seiten wird die index.html weggelassen, sodass die URL wie markup/rest/ aussehen würde.

name = 'dirhtml'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Hinzugefügt in Version 0.6.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder[source]¶

Dies ist ein HTML-Builder, der das gesamte Projekt in einer einzigen Ausgabedatei zusammenfasst. (Offensichtlich funktioniert dies nur bei kleineren Projekten.) Die Datei wird wie das Hauptdokument benannt. Es werden keine Indizes generiert.

name = 'singlehtml'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Hinzugefügt in Version 1.0.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder[source]¶

Dieser Builder erzeugt die gleiche Ausgabe wie der Standalone HTML-Builder, generiert aber auch HTML Help-Supportdateien, die es dem Microsoft HTML Help Workshop ermöglichen, sie zu einer CHM-Datei zu kompilieren.

name = 'htmlhelp'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

class sphinxcontrib.qthelp.QtHelpBuilder[source]¶

Dieser Builder erzeugt die gleiche Ausgabe wie der Standalone HTML-Builder, generiert aber auch Qt Help-Sammlungsunterstützungsdateien, die es dem Qt-Sammlungsgenerator ermöglichen, sie zu kompilieren.

Geändert in Version 2.0: Von Paket sphinx.builders nach sphinxcontrib.qthelp verschoben.

name = 'qthelp'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

class sphinxcontrib.applehelp.AppleHelpBuilder[source]¶

Dieser Builder erzeugt ein Apple Help Book basierend auf der gleichen Ausgabe wie der Standalone HTML-Builder.

Wenn das Quellverzeichnis .lproj-Ordner enthält, werden die Inhalte des Ordners, der der ausgewählten Sprache entspricht, mit der generierten Ausgabe zusammengeführt. Diese Ordner werden von allen anderen Dokumentationstypen ignoriert.

Um ein gültiges Hilfebuch zu erstellen, benötigt dieser Builder das Kommandozeilenwerkzeug hiutil, das nur auf Mac OS X 10.6 und höher verfügbar ist. Sie können den Indexierungsschritt deaktivieren, indem Sie applehelp_disable_external_tools auf True setzen. In diesem Fall ist die Ausgabe erst gültig, wenn hiutil für alle .lproj-Ordner im Bundle ausgeführt wurde.

name = 'applehelp'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Hinzugefügt in Version 1.3.

Geändert in Version 2.0: Von Paket sphinx.builders nach sphinxcontrib.applehelp verschoben.

class sphinxcontrib.devhelp.DevhelpBuilder[source]¶

Dieser Builder erzeugt die gleiche Ausgabe wie der Standalone HTML-Builder, generiert aber auch eine GNOME Devhelp-Supportdatei, die es dem GNOME Devhelp-Reader ermöglicht, sie anzuzeigen.

name = 'devhelp'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Geändert in Version 2.0: Von Paket sphinx.builders nach sphinxcontrib.devhelp verschoben.

class sphinx.builders.epub3.Epub3Builder[source]¶

Dieser Builder erzeugt die gleiche Ausgabe wie der Standalone HTML-Builder, generiert aber auch eine *epub*-Datei für E-Book-Reader. Details dazu finden Sie in Epub-Informationen. Die Definition des Epub-Formats finden Sie unter https://idpf.org/epub oder https://en.wikipedia.org/wiki/EPUB. Der Builder erstellt *EPUB 3*-Dateien.

name = 'epub'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Hinzugefügt in Version 1.4.

Geändert in Version 1.5: Seit Sphinx 1.5 wird der epub3-Builder als Standard-Epub-Builder verwendet.

class sphinx.builders.latex.LaTeXBuilder[source]¶

Dieser Builder erzeugt LaTeX-Quelldateien im Ausgabeverzeichnis. Die eigentlichen PDF-Erstellungen finden innerhalb dieses Ausgabeverzeichnisses statt und müssen in einem zweiten Schritt ausgelöst werden. Dies kann über make all-pdf dort erfolgen. Um die beiden Schritte zu einem einzigen zusammenzufassen, verwenden Sie sphinx-build -M (d. h. -M latexpdf, nicht -b latexpdf) oder make latexpdf im Stammverzeichnis des Projekts.

Siehe latex_documents und das Kapitel Optionen für LaTeX-Ausgabe für verfügbare Optionen.

PDF-Erstellungen benötigen eine ausreichend vollständige LaTeX-Installation. Das Testen erfolgt derzeit (seit 5.3.0) auf Ubuntu 22.04LTS, dessen LaTeX-Distribution (Stand 2022/02/04) TeXLive 2021 entspricht, aber PDF-Erstellungen können auch mit viel älteren LaTeX-Installationen erfolgreich durchgeführt werden.

Auf jeden Fall müssen unter Ubuntu beispielsweise die folgenden Pakete alle vorhanden sein

texlive-latex-recommended
texlive-fonts-recommended
texlive-fonts-extra (benötigt für fontawesome5, siehe die Änderungsmitteilung 7.4.0 unten)
tex-gyre (wenn latex_engine auf Standard belassen wird)
texlive-latex-extra
latexmk

Geändert in Version 4.0.0: TeX Gyre-Schriften sind nun für die 'pdflatex'-Engine (Standard) erforderlich.

Geändert in Version 7.4.0: Das LaTeX-Paket xcolor ist jetzt erforderlich (es ist ohnehin Teil von Ubuntu texlive-latex-recommended). Das LaTeX-Paket fontawesome5 wird empfohlen. Weitere Informationen finden Sie im ‚sphinxsetup‘-Schlüssel iconpackage.

Zusätzliche Pakete sind unter bestimmten Umständen erforderlich

texlive-lang-cyrillic für Kyrillisch (und dann auch cm-super bei Verwendung der Standardschriften),
texlive-lang-greek für Griechisch (und dann auch cm-super bei Verwendung der Standardschriften),
texlive-xetex, wenn latex_engine 'xelatex' ist,
texlive-luatex, wenn latex_engine 'lualatex' ist,
fonts-freefont-otf, wenn latex_engine entweder 'xelatex' oder 'lualatex' ist.

Hinweis

Seit 1.6 verwendet make latexpdf unter GNU/Linux und macOS latexmk, da dies sicherstellt, dass die benötigte Anzahl von Durchläufen automatisch ausgeführt wird. Unter Windows führen die PDF-Erstellungen eine feste Anzahl von LaTeX-Durchläufen aus (drei, dann makeindex, dann zwei weitere).

Man kann latexmk-Optionen über die Makefile-Variable LATEXMKOPTS übergeben. Zum Beispiel

make latexpdf LATEXMKOPTS="-silent"

reduziert die Konsolenausgabe auf ein Minimum.

Außerdem beschleunigt LATEXMKOPTS="-xelatex" bei Version 4.52b oder höher (Januar 2017) von latexmk die PDF-Erstellung über XeLateX bei zahlreichen Grafikeinbindungen.

Um Optionen direkt an die Binärdatei (pdf|xe|lua)latex zu übergeben, verwenden Sie die Variable LATEXOPTS, zum Beispiel

make latexpdf LATEXOPTS="--halt-on-error"

name = 'latex'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'latex'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Beachten Sie, dass ein direkter PDF-Builder von rinohtype bereitgestellt wird. Der Name des Builders lautet rinoh. Details finden Sie im rinohtype-Handbuch.

class sphinx.builders.text.TextBuilder[source]¶

Dieser Builder erstellt für jede reStructuredText-Datei eine Textdatei. Dies ist fast dasselbe wie die reStructuredText-Quelle, aber mit einem Großteil der Markup-Entfernung für bessere Lesbarkeit.

name = 'text'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'text'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Hinzugefügt in Version 0.4.

class sphinx.builders.manpage.ManualPageBuilder[source]¶

Dieser Builder erzeugt Manual Pages im groff-Format. Sie müssen über die Konfigurationsvariable man_pages angeben, welche Dokumente in welche Manual Pages aufgenommen werden sollen.

name = 'man'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'man'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Hinzugefügt in Version 1.0.

class sphinx.builders.texinfo.TexinfoBuilder[source]¶

Dieser Builder erzeugt Texinfo-Dateien, die mit dem Programm makeinfo zu Info-Dateien verarbeitet werden können. Sie müssen über die Konfigurationsvariable texinfo_documents angeben, welche Dokumente in welche Texinfo-Dateien aufgenommen werden sollen.

Das Info-Format ist die Grundlage für das Online-Hilfesystem von GNU Emacs und das terminalbasierte Programm info. Weitere Details finden Sie in Texinfo-Informationen. Das Texinfo-Format ist das offizielle Dokumentationssystem des GNU-Projekts. Weitere Informationen zu Texinfo finden Sie unter https://www.gnu.org/software/texinfo/.

name = 'texinfo'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'texinfo'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/png', 'image/jpeg', 'image/gif']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Hinzugefügt in Version 1.1.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder[source]¶

Dieser Builder verwendet ein Modul, das die Python-Serialisierungs-API (pickle, simplejson, phpserialize und andere) implementiert, um die generierte HTML-Dokumentation zu speichern. Der Pickle-Builder ist eine Unterklasse davon.

Eine konkrete Unterklasse dieses Builders, die in das PHP-Serialisierungsformat serialisiert, könnte wie folgt aussehen

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'

implementation¶: Ein Modul, das die Funktionen dump(), load(), dumps() und loads() implementiert, die den Funktionen mit denselben Namen aus dem Pickle-Modul entsprechen. Bekannte Module, die diese Schnittstelle implementieren, sind simplejson, phpserialize, plistlib und andere.

out_suffix¶: Die Endung für alle regulären Dateien.

globalcontext_filename¶: Der Dateiname für die Datei, die den „globalen Kontext“ enthält. Dies ist ein Dictionary mit einigen allgemeinen Konfigurationswerten, wie z. B. dem Namen des Projekts.

searchindex_filename¶: Der Dateiname für den Suchindex, den Sphinx generiert.

Details zum Ausgabeformat finden Sie unter Details zu Serialisierungs-Buildern.

Hinzugefügt in Version 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder[source]¶

Dieser Builder erstellt ein Verzeichnis mit Pickle-Dateien, die hauptsächlich HTML-Fragmente und TOC-Informationen enthalten, für die Verwendung durch eine Webanwendung (oder ein benutzerdefiniertes Nachbearbeitungstool), das keine Standard-HTML-Vorlagen verwendet.

Details zum Ausgabeformat finden Sie unter Details zu Serialisierungs-Buildern.

name = 'pickle'¶

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

Der alte Name web funktioniert ebenfalls noch.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Die Dateiendung lautet .fpickle. Der globale Kontext heißt globalcontext.pickle, der Suchindex searchindex.pickle.

Klasse sphinxcontrib.serializinghtml.JSONHTMLBuilder[Quelle]¶

Dieser Builder erstellt ein Verzeichnis mit JSON-Dateien, die hauptsächlich HTML-Fragmente und TOC-Informationen enthalten, für die Verwendung einer Webanwendung (oder eines benutzerdefinierten Nachbearbeitungswerkzeugs), das keine Standard-HTML-Vorlagen verwendet.

Details zum Ausgabeformat finden Sie unter Details zu Serialisierungs-Buildern.

name = 'json'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'html'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: Die Liste der MIME-Typen von Bildformaten, die vom Builder unterstützt werden. Bilddateien werden in der Reihenfolge durchsucht, in der sie hier erscheinen.

Die Dateiendung ist .fjson. Der globale Kontext heißt globalcontext.json, der Suchindex searchindex.json.

Hinzugefügt in Version 0.5.

Klasse sphinx.builders.gettext.MessageCatalogBuilder[Quelle]¶

Dieser Builder erstellt gettext-Stil Nachrichtenkataloge. Jede oberste Ebene Datei oder Unterverzeichnis erzeugt eine einzelne .pot Katalogvorlage.

Siehe die Dokumentation zur Internationalisierung für weitere Referenzen.

name = 'gettext'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = ''¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Hinzugefügt in Version 1.1.

Klasse sphinx.builders.changes.ChangesBuilder[Quelle]¶

Dieser Builder erstellt eine HTML-Übersicht aller versionadded, versionchanged, deprecated und versionremoved Direktiven für die aktuelle version. Dies ist beispielsweise nützlich, um eine Changelog-Datei zu generieren.

name = 'changes'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = ''¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Klasse sphinx.builders.dummy.DummyBuilder[Quelle]¶

Dieser Builder erzeugt keine Ausgabe. Die Eingabe wird nur geparst und auf Konsistenz geprüft. Dies ist nützlich für Linting-Zwecke.

name = 'dummy'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

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

Hinzugefügt in Version 1.4.

Klasse sphinx.builders.linkcheck.CheckExternalLinksBuilder[Quelle]¶

Dieser Builder scannt alle Dokumente nach externen Links, versucht, sie mit requests zu öffnen, und schreibt eine Übersicht darüber, welche defekt sind und weitergeleitet wurden, auf die Standardausgabe und in output.txt im Ausgabeverzeichnis.

name = 'linkcheck'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = ''¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Geändert in Version 1.5: Seit Sphinx 1.5 verwendet der Linkcheck-Builder das requests-Modul.

Geändert in Version 3.4: Der Linkcheck-Builder versucht Links erneut, wenn Server Ratenbegrenzungen anwenden.

Klasse sphinx.builders.xml.XMLBuilder[Quelle]¶

Dieser Builder erzeugt Docutils-native XML-Dateien. Die Ausgabe kann mit Standard-XML-Tools wie XSLT-Prozessoren in beliebige Endformen transformiert werden.

name = 'xml'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'xml'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Hinzugefügt in Version 1.2.

Klasse sphinx.builders.xml.PseudoXMLBuilder[Quelle]¶

Dieser Builder wird für das Debugging der Sphinx/Docutils "Reader to Transform to Writer"-Pipeline verwendet. Er erzeugt kompakte, schön formatierte "Pseudo-XML"-Dateien, bei denen die Verschachtelung durch Einrückung angezeigt wird (keine End-Tags). Externe Attribute für alle Elemente werden ausgegeben, und interne Attribute für alle verbleibenden "ausstehenden" Elemente werden ebenfalls angegeben.

name = 'pseudoxml'¶: Der Name des Builders. Dies ist der Wert, der verwendet wird, um Builder auf der Kommandozeile auszuwählen.

format = 'pseudoxml'¶: Das Ausgabeformat des Builders oder „“, wenn keine Dokumentenausgabe erzeugt wird. Dies ist üblicherweise die Dateiendung, z. B. „html“, obwohl jeder beliebige Zeichenkettenwert akzeptiert wird. Die Formatzeichenkette des Builders kann von verschiedenen Komponenten wie SphinxPostTransform oder Extensions verwendet werden, um ihre Kompatibilität mit dem Builder zu bestimmen.

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

Hinzugefügt in Version 1.2.

In Sphinx integrierte Erweiterungen, die weitere Builder anbieten, sind

Details des Serialisierungs-Builders¶

Alle Serialisierungs-Builder geben eine Datei pro Quelldatei und einige spezielle Dateien aus. Sie kopieren auch die reStructuredText-Quelldateien in das Verzeichnis _sources unterhalb des Ausgabeverzeichnisses.

Der PickleHTMLBuilder ist eine integrierte Unterklasse, die die Pickle-Serialisierungsschnittstelle implementiert.

Die Dateien pro Quelldatei haben die Endungen von out_suffix und sind in Verzeichnissen angeordnet, genau wie die Quelldateien. Sie deserialisieren zu einem Dictionary (oder einer dictionary-ähnlichen Struktur) mit diesen Schlüsseln

body: Der HTML-„Body“ (d. h. die HTML-Darstellung der Quelldatei), wie vom HTML-Translator gerendert.
title: Der Titel des Dokuments, als HTML (kann Markup enthalten).
toc: Das Inhaltsverzeichnis für die Datei, gerendert als HTML <ul>.
display_toc: Ein boolescher Wert, der True ist, wenn der toc mehr als einen Eintrag enthält.
current_page_name: Der Dokumentenname der aktuellen Datei.
parents, prev und next: Informationen über verwandte Kapitel im TOC-Baum. Jede Beziehung ist ein Dictionary mit den Schlüsseln link (HREF für die Beziehung) und title (Titel des verwandten Dokuments, als HTML). parents ist eine Liste von Beziehungen, während prev und next eine einzelne Beziehung sind.
sourcename: Der Name der Quelldatei unter _sources.

Die speziellen Dateien befinden sich im Stammverzeichnis des Ausgabeverzeichnisses. Sie sind

SerializingHTMLBuilder.globalcontext_filename

Ein gepickeltes Dictionary mit diesen Schlüsseln

project, copyright, release, version: Dieselbe Werte wie in der Konfigurationsdatei angegeben.
style: html_style.
last_updated: Datum des letzten Builds.
builder: Name des verwendeten Builders, bei Pickles ist dies immer 'pickle'.
titles: Ein Dictionary aller Dokumententitel als HTML-Strings.

SerializingHTMLBuilder.searchindex_filename

Ein Index, der zum Durchsuchen der Dokumentation verwendet werden kann. Es ist eine gepickelte Liste mit diesen Einträgen

Eine Liste indizierter Dokumentennamen.
Eine Liste von Dokumenttiteln als HTML-Strings in derselben Reihenfolge wie die erste Liste.
Ein Dictionary, das Wortwurzeln (verarbeitet von einem englischsprachigen Stemmer) auf eine Liste von Ganzzahlen abbildet, die Indizes in der ersten Liste sind.

environment.pickle

Die Build-Umgebung. Dies ist immer eine Pickle-Datei, unabhängig vom Builder und eine Kopie der Umgebung, die verwendet wurde, als der Builder gestartet wurde.

Im Gegensatz zu den anderen Pickle-Dateien erfordert diese Pickle-Datei, dass das Paket sphinx beim Entpickeln verfügbar ist.