sphinx-build¶

Zusammenfassung¶

sphinx-build [Optionen] <Quellverzeichnis> <Ausgabeverzeichnis> [Dateinamen …]

Beschreibung¶

sphinx-build generiert Dokumentation aus den Dateien im Verzeichnis <Quellverzeichnis> und platziert sie im Verzeichnis <Ausgabeverzeichnis>.

sphinx-build sucht nach den Konfigurationseinstellungen in <Quellverzeichnis>/conf.py. sphinx-quickstart(1) kann verwendet werden, um Vorlagendateien zu generieren, einschließlich conf.py.

sphinx-build kann Dokumentationen in verschiedenen Formaten erstellen. Ein Format wird durch Angabe des Builder-Namens in der Befehlszeile ausgewählt; standardmäßig ist dies HTML. Builder können auch andere Aufgaben im Zusammenhang mit der Dokumentationsverarbeitung ausführen. Eine Liste der verfügbaren Builder finden Sie unter Builder.

Standardmäßig wird alles erstellt, was veraltet ist. Nur für ausgewählte Dateien kann die Ausgabe erstellt werden, indem einzelne Dateinamen angegeben werden.

Optionen¶

-M buildername¶

Wählt einen Builder im *Make-Modus* aus. Eine Liste aller integrierten Builder von Sphinx finden Sie unter Builder. Erweiterungen können eigene Builder hinzufügen.

Wichtig

Sphinx erkennt die Option -M nur, wenn sie zusammen mit den Quell- und Ausgabeverzeichnissen als erste Option angegeben wird, bevor weitere Optionen übergeben werden. Zum Beispiel:

sphinx-build -M html ./source ./build --fail-on-warning

Der *Make-Modus* bietet die gleiche Build-Funktionalität wie ein standardmäßiges Makefile oder Make.bat und bietet die folgenden zusätzlichen Build-Pipelines:

latexpdf: Erstellt LaTeX-Dateien und führt sie mit pdflatex aus oder gemäß der Einstellung latex_engine. Wenn language auf 'ja' gesetzt ist, wird die LaTeX-zu-PDF-Pipeline platex/dvipdfmx automatisch verwendet.
info: Erstellt Texinfo-Dateien und führt sie mit makeinfo aus.
help: Gibt eine Liste der gültigen Builder-Ziele aus und beendet sich.

Hinweis

Die Standardausgabeverzeichnisse im *Make-Modus* unterscheiden sich von den Standardverzeichnissen bei Verwendung von -b.

doctrees werden in <Ausgabeverzeichnis>/doctrees gespeichert
Ausgabedateien werden in <Ausgabeverzeichnis>/<Buildername> gespeichert

Hinzugefügt in Version 1.2.1.

-b buildername, --builder buildername¶

Wählt einen Builder aus.

Eine Liste aller integrierten Builder von Sphinx finden Sie unter Builder. Erweiterungen können eigene Builder hinzufügen.

Geändert in Version 7.3: Option --builder als Langform hinzugefügt.

-a, --write-all¶: Wenn angegeben, werden immer alle Ausgabedateien geschrieben. Standardmäßig werden nur Ausgabedateien für neue und geänderte Quelldateien geschrieben. (Dies gilt möglicherweise nicht für alle Builder.)

Hinweis

Diese Option liest die Quelldateien nicht erneut ein. Um jede Datei zu lesen und neu zu verarbeiten, verwenden Sie stattdessen --fresh-env.

Geändert in Version 7.3: Option --write-all als Langform hinzugefügt.

-E, --fresh-env¶: Verwendet keine gespeicherte Umgebung (die Struktur, die alle Querverweise speichert), sondern baut sie komplett neu auf. Standardmäßig werden nur Quelldateien gelesen und analysiert, die neu sind oder sich seit dem letzten Lauf geändert haben.

Geändert in Version 7.3: Option --fresh-env als Langform hinzugefügt.

-t tag, --tag tag¶: Definiert das Tag *tag*. Dies ist relevant für only-Direktiven, die ihren Inhalt nur einbeziehen, wenn bestimmte Tags gesetzt sind. Weitere Details finden Sie unter Inhalt basierend auf Tags einfügen.

Hinzugefügt in Version 0.6.

Geändert in Version 7.3: Option --tag als Langform hinzugefügt.

-d path, --doctree-dir path¶: Da Sphinx alle Quelldateien lesen und parsen muss, bevor es eine Ausgabedatei schreiben kann, werden die geparsten Quelldateien als „doctree pickles“ zwischengespeichert. Normalerweise werden diese Dateien in einem Verzeichnis namens .doctrees unter dem Build-Verzeichnis abgelegt; mit dieser Option können Sie ein anderes Cache-Verzeichnis auswählen (die Doctrees können zwischen allen Buildern gemeinsam genutzt werden).

Geändert in Version 7.3: Option --doctree-dir als Langform hinzugefügt.

-j N, --jobs N¶: Verteilt den Build über *N* parallele Prozesse, um das Erstellen auf Mehrprozessormaschinen effektiver zu gestalten. Diese Funktion funktioniert nur auf Systemen, die „fork“ unterstützen. Windows wird nicht unterstützt. Beachten Sie, dass nicht alle Teile und nicht alle Builder von Sphinx parallelisiert werden können. Wenn das Argument auto angegeben wird, verwendet Sphinx die Anzahl der CPUs als *N*. Standardmäßig ist es 1.

Hinzugefügt in Version 1.2: Diese Option sollte als *experimentell* betrachtet werden.

Geändert in Version 1.7: Unterstützung für das Argument auto.

Geändert in Version 6.2: Option --jobs als Langform hinzugefügt.

-c path, --conf-dir path¶: Sucht nicht im Quellverzeichnis nach conf.py, sondern verwendet stattdessen das angegebene Konfigurationsverzeichnis. Beachten Sie, dass verschiedene andere Dateien und Pfade, die durch Konfigurationswerte angegeben werden, relativ zum Konfigurationsverzeichnis erwartet werden und daher auch an diesem Speicherort vorhanden sein müssen.

Hinzugefügt in Version 0.3.

Geändert in Version 7.3: Option --conf-dir als Langform hinzugefügt.

-C, --isolated¶: Sucht nicht nach einer Konfigurationsdatei; nimmt Optionen nur über die Option --define entgegen.

Hinzugefügt in Version 0.5.

Geändert in Version 7.3: Option --isolated als Langform hinzugefügt.

-D setting=value, --define setting=value¶

Überschreibt einen Konfigurationswert, der in der Datei conf.py gesetzt wurde. Der Wert muss eine Zahl, ein String, eine Liste oder ein Dictionary sein.

Für Listen können Sie Elemente mit einem Komma trennen, z. B.: -D html_theme_path=pfad1,pfad2.

Für Dictionary-Werte geben Sie den Setting-Namen und den Schlüssel an, z. B.: -D latex_elements.docclass=scrartcl.

Für boolesche Werte verwenden Sie 0 oder 1 als Wert.

Geändert in Version 0.6: Der Wert kann jetzt ein Dictionary sein.

Geändert in Version 1.3: Der Wert kann jetzt auch eine Liste sein.

Geändert in Version 7.3: Option --define als Langform hinzugefügt.

-A name=value, --html-define name=value¶: Weist den HTML-Vorlagen die Variable *name* mit dem Wert *value* zu.

Hinzugefügt in Version 0.5.

Geändert in Version 7.3: Option --html-define als Langform hinzugefügt.

-n, --nitpicky¶: Ausführung im nitpicky-Modus. Derzeit werden Warnungen für alle fehlenden Referenzen generiert. Eine Möglichkeit, einige Referenzen als „bekanntermaßen fehlend“ auszuschließen, finden Sie unter dem Konfigurationswert nitpick_ignore.

Geändert in Version 7.3: Option --nitpicky als Langform hinzugefügt.

-N, --no-color¶: Keine farbige Ausgabe erzeugen.

Geändert in Version 1.6: Option --no-color als Langform hinzugefügt.

--color¶: Farbige Ausgabe erzeugen. Standardmäßig automatisch erkannt.

Hinzugefügt in Version 1.6.

-v, --verbose¶: Erhöht die Ausführlichkeit (Logging-Stufe). Diese Option kann bis zu dreimal angegeben werden, um mehr Debug-Ausgaben zu erhalten. Sie impliziert -T.

Hinzugefügt in Version 1.2.

Geändert in Version 7.3: Option --verbose als Langform hinzugefügt.

-q, --quiet¶: Gibt nichts auf der Standardausgabe aus, schreibt nur Warnungen und Fehler auf die Standardfehlerausgabe.

Geändert in Version 7.3: Option --quiet als Langform hinzugefügt.

-Q, --silent¶: Gibt nichts auf der Standardausgabe aus und unterdrückt auch Warnungen. Nur Fehler werden auf die Standardfehlerausgabe geschrieben.

Geändert in Version 7.3: Option --silent als Langform hinzugefügt.

-w file, --warning-file file¶: Schreibt Warnungen (und Fehler) in die angegebene Datei, zusätzlich zur Standardfehlerausgabe.

Geändert in Version 7.3: ANSI-Steuersequenzen werden beim Schreiben in die Datei *file* entfernt.

Geändert in Version 7.3: Option --warning-file als Langform hinzugefügt.

-W, --fail-on-warning¶: Wandelt Warnungen in Fehler um. Das bedeutet, dass sphinx-build mit dem Exit-Status 1 beendet wird, wenn während des Builds Warnungen generiert werden.

Geändert in Version 7.3: Option --fail-on-warning als Langform hinzugefügt.

Geändert in Version 8.1: sphinx-build beendet sich nicht mehr beim ersten Warnhinweis, sondern führt den gesamten Build aus und beendet sich mit dem Exit-Status 1, wenn Warnungen generiert wurden. Dieses Verhalten wurde zuvor mit --keep-going aktiviert.

--keep-going¶: Ab Sphinx 8.1 ist --keep-going immer aktiviert. Zuvor war es nur in Verbindung mit --fail-on-warning anwendbar, das standardmäßig sphinx-build beim ersten Warnhinweis beendete. Die Verwendung von --keep-going führt sphinx-build bis zum Abschluss aus und beendet sich mit dem Exit-Status 1, wenn Fehler auftreten.

Hinzugefügt in Version 1.8.

Geändert in Version 8.1: sphinx-build beendet sich nicht mehr beim ersten Warnhinweis, was bedeutet, dass --keep-going effektiv immer aktiviert ist. Die Option bleibt aus Kompatibilitätsgründen erhalten, könnte aber zu einem späteren Zeitpunkt entfernt werden.

-T, --show-traceback¶: Zeigt den vollständigen Traceback an, wenn eine unbehandelte Ausnahme auftritt. Andernfalls wird nur eine Zusammenfassung angezeigt und die Traceback-Informationen werden für eine weitere Analyse in eine Datei gespeichert.

Hinzugefügt in Version 1.2.

Geändert in Version 7.3: Option --show-traceback als Langform hinzugefügt.

-P, --pdb¶: (Nur zum Debuggen nützlich.) Führt den Python-Debugger pdb aus, wenn während des Builds eine unbehandelte Ausnahme auftritt.

Geändert in Version 7.3: Option --pdb als Langform hinzugefügt.

--exception-on-warning¶: Löst eine Ausnahme aus, wenn während des Builds eine Warnung ausgegeben wird. Dies kann in Kombination mit --pdb nützlich sein, um Warnungen zu debuggen.

Hinzugefügt in Version 8.1.

-h, --help, --version¶: Zeigt eine Nutzungszusammenfassung oder die Sphinx-Version an.

Hinzugefügt in Version 1.2.

Sie können auch einen oder mehrere Dateinamen nach den Quell- und Build-Verzeichnissen in der Befehlszeile angeben. Sphinx versucht dann, nur diese Ausgabedateien (und ihre Abhängigkeiten) zu erstellen.

Umgebungsvariablen¶

sphinx-build bezieht sich auf die folgenden Umgebungsvariablen:

MAKE: Ein Pfad zu einem Make-Befehl. Auch ein Befehlsname ist zulässig. sphinx-build verwendet ihn, um Unter-Build-Prozesse im Make-Modus aufzurufen.

Makefile-Optionen

Die von sphinx-quickstart erstellten Dateien Makefile und make.bat führen normalerweise sphinx-build nur mit den Optionen -b und -d aus. Sie unterstützen jedoch die folgenden Variablen zur Anpassung des Verhaltens:

PAPER: Dies setzt den Schlüssel 'papersize' von latex_elements: d. h. PAPER=a4 setzt ihn auf 'a4paper' und PAPER=letter auf 'letterpaper'.

Hinweis

Die Verwendung dieser Umgebungsvariablen war ab Sphinx 1.5 fehlerhaft, da a4 oder letter anstelle des benötigten a4paper bzw. letterpaper als Option für das LaTeX-Dokument landeten. Ab 1.7.7 behoben.

SPHINXBUILD: Der Befehl, der anstelle von sphinx-build verwendet werden soll.

BUILDDIR: Das Build-Verzeichnis, das anstelle des in sphinx-quickstart ausgewählten Verzeichnisses verwendet werden soll.

SPHINXOPTS: Zusätzliche Optionen für sphinx-build. Diese Optionen können auch über die Kurzvariablen **O** (Großbuchstabe 'o') gesetzt werden.

NO_COLOR: Wenn gesetzt (unabhängig vom Wert), verwendet sphinx-build keine Farbe in der Terminalausgabe. NO_COLOR hat Vorrang vor FORCE_COLOR. Weitere Bibliotheken, die diesen Community-Standard unterstützen, finden Sie unter no-color.org.

Hinzugefügt in Version 4.5.0.

FORCE_COLOR: Wenn gesetzt (unabhängig vom Wert), verwendet sphinx-build Farbe in der Terminalausgabe. NO_COLOR hat Vorrang vor FORCE_COLOR.

Hinzugefügt in Version 4.5.0.

Veraltet-Meldungen¶

Wenn beim Erstellen der Dokumentation eines Benutzers Veraltet-Meldungen wie RemovedInSphinxXXXWarning angezeigt werden, verwendet eine Sphinx-Erweiterung veraltete Funktionen. In diesem Fall melden Sie dies bitte dem Autor der Erweiterung.

Um die Veraltet-Meldungen zu deaktivieren, setzen Sie die Umgebungsvariable PYTHONWARNINGS= in Ihrer Umgebung. Zum Beispiel:

PYTHONWARNINGS= make html (Linux/Mac)
export PYTHONWARNINGS= und dann make html (Linux/Mac)
set PYTHONWARNINGS= und dann make html (Windows)
Ändern Sie Ihr Makefile/make.bat und setzen Sie die Umgebungsvariable.

Siehe auch¶

sphinx-quickstart(1)