Konfiguration¶

Das Konfigurationsverzeichnis muss eine Datei namens conf.py enthalten. Diese Datei (die Python-Code enthält) wird als "Build-Konfigurationsdatei" bezeichnet und enthält (fast) alle Konfigurationen, die zur Anpassung des Sphinx-Eingabe- und Ausgabe-Verhaltens erforderlich sind.

Eine optionale Datei docutils.conf kann dem Konfigurationsverzeichnis hinzugefügt werden, um die Docutils-Konfiguration anzupassen, falls diese nicht anderweitig überschrieben oder von Sphinx festgelegt wird.

Wichtige Hinweise

Sofern nicht anders dokumentiert, müssen Werte Zeichenketten sein, und ihr Standardwert ist die leere Zeichenkette.
Der Begriff "vollqualifizierter Name" (FQN) bezieht sich auf eine Zeichenkette, die ein importierbares Python-Objekt innerhalb eines Moduls benennt; zum Beispiel bedeutet der vollqualifizierte Name "sphinx.builders.Builder" die Klasse Builder im Modul sphinx.builders.
Dokumentennamen verwenden / als Pfadtrennzeichen und enthalten keine Dateinamenerweiterung.

Wo glob-ähnliche Muster zulässig sind, können Sie die Standard-Shell-Konstrukte (*, ?, [...] und [!...]) verwenden, wobei keines dieser Zeichen Schrägstriche (/) abgleicht. Ein doppelter Stern ** kann verwendet werden, um jede Zeichensequenz abzugleichen, *einschließlich* von Schrägstrichen.

Tipp

Die Konfigurationsdatei wird zur Build-Zeit als Python-Code ausgeführt (unter Verwendung von importlib.import_module(), wobei das aktuelle Verzeichnis auf das Konfigurationsverzeichnis gesetzt wird), und kann daher beliebig komplexen Code ausführen.

Sphinx liest dann einfache Namen aus dem Namensraum der Datei als seine Konfiguration. Im Allgemeinen sollten Konfigurationswerte einfache Zeichenketten, Zahlen oder Listen oder Wörterbücher von einfachen Werten sein.

Der Inhalt des Konfigurationsnamensraums wird gepickelt (damit Sphinx Änderungen an der Konfiguration erkennen kann), daher darf er keine unpickle-baren Werte enthalten – löschen Sie sie gegebenenfalls mit del aus dem Namensraum. Module werden automatisch entfernt, daher ist das Löschen importierter Module nicht erforderlich.

Projekt-Tags¶

Es gibt ein spezielles Objekt namens tags, das in der Konfigurationsdatei verfügbar ist und die Projekt-Tags bereitstellt. Tags werden entweder über die Befehlszeilenoption --tag oder tags.add('tag') definiert. Beachten Sie, dass der Builder-Name und die Format-Tags in conf.py nicht verfügbar sind.

Es kann verwendet werden, um die definierten Tags wie folgt abzufragen und zu ändern

Um abzufragen, ob ein Tag gesetzt ist, verwenden Sie 'tag' in tags.
Um einen Tag hinzuzufügen, verwenden Sie tags.add('tag').
Um einen Tag zu entfernen, verwenden Sie tags.remove('tag').

Projektinformationen¶

project¶

Typ:: str
Standard:: 'Projektname nicht gesetzt'

Der Name des dokumentierten Projekts. Beispiel

project = 'Thermidor'

author¶

Typ:: str
Standard:: 'Autorname nicht gesetzt'

Der/die Autor(en) des Projekts. Beispiel

author = 'Joe Bloggs'

copyright¶

project_copyright¶

Typ:: str | Sequence[str]
Standard:: ''

Eine Copyright-Erklärung. Zulässige Stile sind wie folgt, wobei 'YYYY' ein vierstelliges Jahr darstellt.

copyright = 'YYYY'
copyright = 'YYYY, Autor Name'
copyright = 'YYYY Autor Name'
copyright = 'YYYY-YYYY, Autor Name'
copyright = 'YYYY-YYYY Autor Name'

Wenn die Zeichenkette '%Y' in einer Copyright-Zeile vorkommt, wird sie durch das aktuelle vierstellige Jahr ersetzt. Zum Beispiel

copyright = '%Y'
copyright = '%Y, Autor Name'
copyright = 'YYYY-%Y, Autor Name'

Hinzugefügt in Version 3.5: Der Alias project_copyright.

Geändert in Version 7.1: Der Wert kann nun eine Sequenz von Copyright-Erklärungen im obigen Format sein, die jeweils auf einer eigenen Zeile angezeigt werden.

Geändert in Version 8.1: Copyright-Erklärungen unterstützen den Platzhalter '%Y'.

version¶

Typ:: str
Standard:: ''

Die Hauptversion des Projekts, die als Ersatz für die Standard-Substitution |version| verwendet wird.

Dies kann etwas sein wie version = '4.2'. Die vollständige Projektversion ist in release definiert.

Wenn Ihr Projekt keine sinnvolle Unterscheidung zwischen einer "vollständigen" und einer "Haupt"-Version macht, setzen Sie sowohl version als auch release auf denselben Wert.

release¶

Typ:: str
Standard:: ''

Die vollständige Projektversion, die als Ersatz für die Standard-Substitution |release| und z. B. in den HTML-Vorlagen verwendet wird.

Dies kann etwas sein wie release = '4.2.1b0'. Die Hauptversion (kurze Version) des Projekts ist in version definiert.

Wenn Ihr Projekt keine sinnvolle Unterscheidung zwischen einer "vollständigen" und einer "Haupt"-Version macht, setzen Sie sowohl version als auch release auf denselben Wert.

Allgemeine Konfiguration¶

needs_sphinx¶

Typ:: str
Standard:: ''

Setzt eine Mindestversion von Sphinx, die für den Build des Projekts erforderlich ist. Das Format sollte eine Versionszeichenkette vom Typ 'major.minor' sein, z. B. '1.1'. Sphinx vergleicht dies mit seiner eigenen Version und weigert sich, das Projekt zu bauen, wenn die laufende Sphinx-Version zu alt ist. Standardmäßig gibt es keine Mindestversion.

Hinzugefügt in Version 1.0.

Geändert in Version 1.4: Erlaubt eine Versionszeichenkette vom Typ 'major.minor.micro'.

extensions¶

Typ:: list[str]
Standard:: []

Eine Liste von Zeichenketten, die Modulnamen von Sphinx-Erweiterungen sind. Dies können Erweiterungen sein, die mit Sphinx gebündelt sind (benannt sphinx.ext.*), oder benutzerdefinierte interne oder externe Erweiterungen.

Um eine Drittanbieter-Erweiterung zu verwenden, müssen Sie sicherstellen, dass sie installiert ist, und sie in die extensions-Liste aufnehmen, wie hier gezeigt

extensions = [
    ...
    'numpydoc',
]

Für interne Erweiterungen gibt es zwei Optionen. Die Konfigurationsdatei selbst kann eine Erweiterung sein; dazu müssen Sie nur eine setup()-Funktion darin bereitstellen. Andernfalls müssen Sie sicherstellen, dass Ihre benutzerdefinierte Erweiterung importierbar ist und sich in einem Verzeichnis befindet, das im Python-Pfad liegt.

Stellen Sie sicher, dass absolute Pfade verwendet werden, wenn Sie sys.path ändern. Wenn sich Ihre benutzerdefinierten Erweiterungen in einem Verzeichnis befinden, das relativ zum Konfigurationsverzeichnis liegt, verwenden Sie pathlib.Path.resolve() wie folgt

import sys
from pathlib import Path

sys.path.append(str(Path('sphinxext').resolve()))

extensions = [
   ...
   'extname',
]

Die oben dargestellte Verzeichnisstruktur würde wie folgt aussehen

<project directory>/
├── conf.py
└── sphinxext/
    └── extname.py

needs_extensions¶

Typ:: dict[str, str]
Standard:: {}

Wenn gesetzt, muss dieser Wert ein Wörterbuch sein, das Versionsanforderungen für Erweiterungen in extensions angibt. Die Versionszeichenketten sollten im Format 'major.minor' sein. Es müssen nicht für alle Erweiterungen Anforderungen angegeben werden, nur für diejenigen, die Sie überprüfen möchten. Beispiel

needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

Dies erfordert, dass die Erweiterung ihre Version in der setup()-Funktion deklariert. Weitere Details finden Sie unter Sphinx API.

Hinzugefügt in Version 1.3.

manpages_url¶

Typ:: str
Standard:: ''

Eine URL, um manpage-Rollen zu referenzieren. Wenn dies auf https://manpages.debian.org/{path} gesetzt ist, verlinkt die Rolle :manpage:`man(1)` zu <https://manpages.debian.org/man(1)>. Die verfügbaren Muster sind

page: Die Handbuchseite (man)
section: Der Handbuchabschnitt (1)
path: Die ursprüngliche Handbuchseite und der angegebene Abschnitt (man(1))

Dies unterstützt auch Handbuchseiten, die als man.1 angegeben sind.

# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

Hinzugefügt in Version 1.7.

today¶

today_fmt¶

Diese Werte bestimmen, wie das aktuelle Datum formatiert wird, das als Ersatz für die Standard-Substitution |today| verwendet wird.

Wenn Sie today auf einen nicht leeren Wert setzen, wird dieser verwendet.
Andernfalls wird die aktuelle Zeit mit time.strftime() und dem in today_fmt angegebenen Format formatiert.

Der Standardwert für today ist '', und der Standardwert für today_fmt ist '%b %d, %Y' (oder, wenn die Übersetzung mit language aktiviert ist, ein äquivalentes Format für die ausgewählte Gebietssprache).

Optionen für die Abbildung von Zahlen¶

numfig¶

Typ:: bool
Standard:: False

Wenn True, werden Abbildungen, Tabellen und Codeblöcke automatisch nummeriert, wenn sie eine Beschriftung haben. Die Rolle numref ist aktiviert. Bisher nur von HTML- und LaTeX-Buildern beachtet.

Hinweis

Der LaTeX-Builder weist immer Nummern zu, unabhängig davon, ob diese Option aktiviert ist oder nicht.

Hinzugefügt in Version 1.3.

numfig_format¶

Typ:: dict[str, str]
Standard:: {}

Ein Wörterbuch, das 'figure', 'table', 'code-block' und 'section' auf Zeichenketten abbildet, die für die Formatierung von Abbildungsnummern verwendet werden. Der Marker %s wird durch die Abbildungsnummer ersetzt.

Die Standardwerte sind

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

Hinzugefügt in Version 1.3.

numfig_secnum_depth¶

Typ:: int
Standard:: 1

Wenn auf 0 gesetzt, werden Abbildungen, Tabellen und Codeblöcke fortlaufend ab 1 nummeriert.
Wenn 1, ist die Nummerierung x.1, x.2, ... wobei x die Abschnittsnummer darstellt. (Wenn kein Oberabschnitt vorhanden ist, wird das Präfix nicht hinzugefügt.) Dies gilt natürlich nur, wenn die Abschnittsnummerierung über die Option :numbered: der toctree-Direktive aktiviert wurde.
Wenn 2, ist die Nummerierung x.y.1, x.y.2, ... wobei x die Abschnittsnummer und y die Unterabschnittsnummer darstellt. Wenn sie direkt unter einem Abschnitt liegt, gibt es kein y.-Präfix, und wenn kein Oberabschnitt vorhanden ist, wird das Präfix nicht hinzugefügt.
Jede andere positive Ganzzahl kann nach den obigen Regeln verwendet werden.

Hinzugefügt in Version 1.3.

Geändert in Version 1.7: Der LaTeX-Builder beachtet diese Einstellung, wenn numfig auf True gesetzt ist.

Optionen für die Hervorhebung¶

highlight_language¶

Typ:: str
Standard:: 'default'

Die Standardsprache für die Hervorhebung von Quellcode. Der Standardwert ist 'default', was Warnungen unterdrückt, wenn die Hervorhebung als Python-Code fehlschlägt.

Der Wert sollte ein gültiger Name für einen Pygments-Lexer sein; weitere Details finden Sie unter Anzeigen von Codebeispielen.

Hinzugefügt in Version 0.5.

Geändert in Version 1.4: Der Standardwert ist nun 'default'.

highlight_options¶

Typ:: dict[str, dict[str, Any]]
Standard:: {}

Ein Wörterbuch, das Pygments-Lexer-Namen ihren Optionen zuordnet. Diese sind Lexer-spezifisch; welche Optionen von jedem verstanden werden, finden Sie in der Pygments-Dokumentation.

Beispiel

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

Hinzugefügt in Version 1.3.

Geändert in Version 3.5: Ermöglicht die Konfiguration von Hervorhebungsoptionen für mehrere Lexer.

pygments_style¶

Typ:: str
Standard:: 'sphinx'

Der Stilname, der für die Pygments-Hervorhebung von Quellcode verwendet wird. Wenn nicht gesetzt, wird entweder der Standardstil des Themas oder 'sphinx' für die HTML-Ausgabe ausgewählt.

Geändert in Version 0.3: Wenn der Wert ein vollqualifizierter Name einer benutzerdefinierten Pygments-Stilklasse ist, wird dieser dann als benutzerdefinierter Stil verwendet.

Optionen für HTTP-Anfragen¶

tls_verify¶

Typ:: bool
Standard:: True

Wenn True, überprüft Sphinx die Serverzertifikate.

Hinzugefügt in Version 1.5.

tls_cacerts¶

Typ:: str | dict[str, str]
Standard:: ''

Ein Pfad zu einer Zertifikatsdatei einer CA oder ein Pfad zu einem Verzeichnis, das die Zertifikate enthält. Dies erlaubt auch ein Wörterbuch, das Hostnamen auf den Zertifikatsdateipfad abbildet. Die Zertifikate werden zur Überprüfung von Serverzertifikaten verwendet.

Hinzugefügt in Version 1.5.

Tipp

Sphinx verwendet requests als HTTP-Bibliothek intern. Wenn tls_cacerts nicht gesetzt ist, greift Sphinx auf das Standardverhalten von requests zurück. Weitere Details finden Sie unter SSL Cert Verification.

user_agent¶

Typ:: str
Standard:: 'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'

Legt den User-Agent fest, der von Sphinx für HTTP-Anfragen verwendet wird.

Hinzugefügt in Version 2.3.

Optionen für die Internationalisierung¶

Diese Optionen beeinflussen die *Native Language Support* von Sphinx. Weitere Details finden Sie in der Dokumentation zur Internationalisierung.

language¶

Typ:: str
Standard:: 'en'

Der Code für die Sprache, in der die Dokumente geschrieben sind. Alle von Sphinx automatisch generierten Texte werden in dieser Sprache sein. Außerdem versucht Sphinx, einzelne Absätze aus Ihren Dokumenten mit den aus locale_dirs erhaltenen Übersetzungssätzen zu ersetzen. Sphinx sucht nach sprachspezifischen Abbildungen, die durch figure_language_filename benannt sind (z. B. ist die deutsche Version von myfigure.png standardmäßig myfigure.de.png) und ersetzt damit die Originalabbildungen. Im LaTeX-Builder wird eine geeignete Sprache als Option für das *Babel*-Paket ausgewählt.

Hinzugefügt in Version 0.5.

Geändert in Version 1.4: Unterstützt Abbildungsersetzung

Geändert in Version 5.0: Der Standardwert ist nun 'en' (zuvor None).

Derzeit von Sphinx unterstützte Sprachen sind

ar – Arabisch
bg – Bulgarisch
bn – Bengali
ca – Katalanisch
cak – Kaqchikel
cs – Tschechisch
cy – Walisisch
da – Dänisch
de – Deutsch
el – Griechisch
en – Englisch (Standard)
eo – Esperanto
es – Spanisch
et – Estnisch
eu – Baskisch
fa – Iranisch
fi – Finnisch
fr – Französisch
he – Hebräisch
hi – Hindi
hi_IN – Hindi (Indien)
hr – Kroatisch
hu – Ungarisch
id – Indonesisch
it – Italienisch
ja – Japanisch
ko – Koreanisch
lt – Litauisch
lv – Lettisch
mk – Mazedonisch
nb_NO – Norwegisch Bokmal
ne – Nepali
nl – Niederländisch
pl – Polnisch
pt – Portugiesisch
pt_BR – Brasilianisches Portugiesisch
pt_PT – Portugiesisch (Portugal)
ro – Rumänisch
ru – Russisch
si – Singhalesisch
sk – Slowakisch
sl – Slowenisch
sq – Albanisch
sr – Serbisch
sr@latin – Serbisch (Lateinisch)
sr_RS – Serbisch (Kyrillisch)
sv – Schwedisch
ta – Tamil
te – Telugu
tr – Türkisch
uk_UA – Ukrainisch
ur – Urdu
vi – Vietnamesisch
zh_CN – Vereinfachtes Chinesisch
zh_TW – Traditionelles Chinesisch

locale_dirs¶

Typ:: list[str]
Standard:: ['locales']

Verzeichnisse, in denen nach zusätzlichen Meldungskatalogen gesucht wird (siehe language), relativ zum Quellverzeichnis. Die Verzeichnisse in diesem Pfad werden vom gettext-Modul durchsucht.

Interne Meldungen werden aus einer Textdomäne von sphinx bezogen. Wenn Sie das Verzeichnis ./locales zu dieser Einstellung hinzufügen, müssen sich die Meldungskataloge (kompiliert aus dem .po-Format mit msgfmt) in ./locales/language/LC_MESSAGES/sphinx.mo befinden. Die Textdomäne einzelner Dokumente hängt von gettext_compact ab.

Hinweis

Die Option -v von sphinx-build ist nützlich, um zu überprüfen, ob die Einstellung locale_dirs wie erwartet funktioniert. Wenn das Verzeichnis des Meldungskatalogs nicht gefunden wird, werden Debugging-Meldungen ausgegeben.

Hinzugefügt in Version 0.5.

Geändert in Version 1.5: Das Verzeichnis locales wird als Standardwert verwendet.

gettext_allow_fuzzy_translations¶

Typ:: bool
Standard:: False

Wenn True, werden „unscharfe“ Meldungen in den Meldungskatalogen für die Übersetzung verwendet.

Hinzugefügt in Version 4.3.

gettext_compact¶

Typ:: bool | str
Standard:: True

Wenn True, ist die Textdomäne eines Dokuments sein Docname, wenn es sich um eine Top-Level-Projektdatei handelt, und andernfalls dessen Basisverzeichnis.
Wenn False, ist die Textdomäne eines Dokuments der vollständige Docname.
Wenn auf einen String gesetzt, ist die Textdomäne jedes Dokuments dieser String, sodass alle Dokumente eine einzige Textdomäne verwenden.

Mit gettext_compact = True landet das Dokument markup/code.rst in der Textdomäne markup. Mit dieser Option auf False gesetzt, ist es markup/code. Mit dieser Option auf 'sample' gesetzt, ist es sample.

Hinzugefügt in Version 1.1.

Geändert in Version 3.3: Zeichenkettenwerte zulassen.

gettext_uuid¶

Typ:: bool
Standard:: False

Wenn True, generiert Sphinx UUID-Informationen zur Versionsverfolgung in Meldungskatalogen. Sie werden verwendet, um

eine UUID-Zeile für jeden msgid in .pot-Dateien hinzuzufügen.
die Ähnlichkeit zwischen neuen msgids und zuvor gespeicherten alten msgids zu berechnen. (Diese Berechnung kann lange dauern.)

Tipp

Wenn Sie die Berechnung beschleunigen möchten, können Sie ein Drittanbieterpaket (Levenshtein) verwenden, indem Sie pip install levenshtein ausführen.

Hinzugefügt in Version 1.3.

gettext_location¶

Typ:: bool
Standard:: True

Wenn True, generiert Sphinx Standortinformationen für Meldungen in Meldungskatalogen.

Hinzugefügt in Version 1.3.

gettext_auto_build¶

Typ:: bool
Standard:: True

Wenn True, baut Sphinx eine .mo-Datei für jede Übersetzungsdatei.

Hinzugefügt in Version 1.3.

gettext_additional_targets¶

Typ:: set[str] | Sequence[str]
Standard:: []

Aktiviert gettext-Übersetzung für bestimmte Elementtypen. Beispiel

gettext_additional_targets = {'literal-block', 'image'}

Die folgenden Elementtypen werden unterstützt

'index' – Indexbegriffe
'literal-block' – Literalblöcke (Annotation :: und Direktive code-block)
'doctest-block' – Doctest-Block
'raw' – Rohinhalt
'image' – URI für Bilder/Figuren

Hinzugefügt in Version 1.3.

Geändert in Version 4.0: Der Alt-Text für Bilder wird standardmäßig übersetzt.

Geändert in Version 7.4: Erlaubt und bevorzugt einen Set-Typ.

figure_language_filename¶

Typ:: str
Standard:: '{root}.{language}{ext}'

Das Dateinamensformat für sprachspezifische Bilder. Die verfügbaren Format-Tokens sind

{root}: der Dateiname, einschließlich jeglicher Pfadkomponenten, ohne die Dateierweiterung. Zum Beispiel: images/filename.
{path}: die Verzeichnispfadkomponente des Dateinamens, mit einem abschließenden Schrägstrich, falls nicht leer. Zum Beispiel: images/.
{basename}: der Dateiname ohne die Verzeichnispfad- oder Dateierweiterungskomponenten. Zum Beispiel: filename.
{ext}: die Dateierweiterung. Zum Beispiel: .png.
{language}: die Übersetzungssprache. Zum Beispiel: en.
{docpath}: die Verzeichnispfadkomponente für das aktuelle Dokument, mit einem abschließenden Schrägstrich, falls nicht leer. Zum Beispiel: dirname/.

Standardmäßig verwendet eine Bilddirektive .. image:: images/filename.png, die ein Bild unter images/filename.png verwendet, den sprachspezifischen Bilddateinamen images/filename.en.png.

Wenn figure_language_filename wie unten angegeben gesetzt ist, wird der sprachspezifische Bilddateiname stattdessen images/en/filename.png lauten.

figure_language_filename = '{path}{language}/{basename}{ext}'

Hinzugefügt in Version 1.4.

Geändert in Version 1.5: Die Tokens {path} und {basename} hinzugefügt.

Geändert in Version 3.2: Der Token {docpath} hinzugefügt.

translation_progress_classes¶

Typ:: bool | 'translated' | 'untranslated'
Standard:: False

Steuert, welche Klassen (falls überhaupt) hinzugefügt werden, um den Übersetzungsfortschritt anzuzeigen. Diese Einstellung würde wahrscheinlich nur von Dokumentationsübersetzern verwendet, um übersetzte und unübersetzte Inhalte schnell anzuzeigen.

True: Fügt die Klassen translated und untranslated zu allen Knoten mit übersetzbarem Inhalt hinzu.
'translated': Fügt nur die Klasse translated hinzu.
'untranslated': Fügt nur die Klasse untranslated hinzu.
False: Fügt keine Klassen hinzu, um den Übersetzungsfortschritt anzuzeigen.

Hinzugefügt in Version 7.1.

Optionen für Markup¶

default_role¶

Typ:: str
Standard:: None

Der Name einer reStructuredText-Rolle (eingebaut oder Sphinx-Erweiterung), die als Standardrolle verwendet wird, d. h. für Text, der mit `wie dies` markiert ist. Dies kann auf 'py:obj' gesetzt werden, um `filter` zu einem Querverweis auf die Python-Funktion „filter“ zu machen.

Die Standardrolle kann jederzeit innerhalb einzelner Dokumente mithilfe der Standarddirektive default-role von reStructuredText festgelegt werden.

Hinzugefügt in Version 0.4.

keep_warnings¶

Typ:: bool
Standard:: False

Behält Warnungen als „Systemnachrichten“-Absätze in den gerenderten Dokumenten. Warnungen werden beim Ausführen von sphinx-build immer auf den Standardfehlerstrom geschrieben, unabhängig von dieser Einstellung.

Hinzugefügt in Version 0.5.

option_emphasise_placeholders¶

Typ:: bool
Standard:: False

Wenn aktiviert, werden Platzhalter in option-Direktiven hervorgehoben. Um literale Klammern anzuzeigen, maskieren Sie sie mit einem Backslash (\{). Zum Beispiel würden option_emphasise_placeholders=True und .. option:: -foption={TYPE} mit hervorgehobenem TYPE gerendert werden.

Hinzugefügt in Version 5.1.

primary_domain¶

Typ:: str
Standard:: 'py'

Der Name der Standard-Domain. Kann auch None sein, um eine Standarddomain zu deaktivieren. Der Standardwert ist 'py' für die Python-Domain.

Objekte in anderen Domains (unabhängig davon, ob der Domainname explizit angegeben oder durch eine default-domain-Direktive ausgewählt wurde) erhalten den expliziten Domainnamen vorangestellt, wenn sie benannt werden (z. B. wenn die Standarddomain C ist, werden Python-Funktionen als „Python function“ und nicht nur als „function“ bezeichnet). Beispiel

primary_domain = 'cpp'

Hinzugefügt in Version 1.0.

rst_epilog¶

Typ:: str
Standard:: ''

Ein String im reStructuredText-Format, der am Ende jeder gelesenen Quelldatei eingefügt wird. Dies ist ein möglicher Ort, um Substitutionen hinzuzufügen, die in jeder Datei verfügbar sein sollen (ein weiterer ist rst_prolog). Beispiel

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

Hinzugefügt in Version 0.6.

rst_prolog¶

Typ:: str
Standard:: ''

Ein String im reStructuredText-Format, der am Anfang jeder gelesenen Quelldatei eingefügt wird. Dies ist ein möglicher Ort, um Substitutionen hinzuzufügen, die in jeder Datei verfügbar sein sollen (ein weiterer ist rst_epilog). Beispiel

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

Hinzugefügt in Version 1.0.

show_authors¶

Typ:: bool
Standard:: False

Ein boolescher Wert, der bestimmt, ob die Direktiven codeauthor und sectionauthor in den erstellten Dateien ausgegeben werden.

trim_footnote_reference_space¶

Typ:: bool
Standard:: False

Entfernt Leerzeichen vor Fußnotenverweisen, die für den reStructuredText-Parser notwendig sind, um die Fußnote zu erkennen, aber im Output nicht gut aussehen.

Hinzugefügt in Version 0.6.

Optionen für Mathematik¶

Diese Optionen steuern die Markup- und Notationsregeln für mathematische Ausdrücke.

math_eqref_format¶

Typ:: str
Standard:: '({number})'

Eine Zeichenkette, die zur Formatierung der Bezeichnungen von Verweisen auf Gleichungen verwendet wird. Der Platzhalter {number} steht für die Gleichungsnummer.

Beispiel: 'Eq.{number}' wird zum Beispiel als Eq.10 gerendert.

Hinzugefügt in Version 1.7.

math_number_all¶

Typ:: bool
Standard:: False

Erzwingt die Nummerierung aller angezeigten Gleichungen. Beispiel

math_number_all = True

Hinzugefügt in Version 1.4.

math_numfig¶

Typ:: bool
Standard:: True

Wenn True, werden angezeigte mathematische Gleichungen seitenübergreifend nummeriert, wenn numfig aktiviert ist. Die Einstellung numfig_secnum_depth wird berücksichtigt. Die Rolle eq, nicht die Rolle numref, muss verwendet werden, um auf Gleichungsnummern zu verweisen.

Hinzugefügt in Version 1.7.

math_numsep¶

Typ:: str
Standard:: '.'

Eine Zeichenkette, die den Trenner zwischen Abschnittsnummern und der Gleichungsnummer definiert, wenn numfig aktiviert ist und numfig_secnum_depth positiv ist.

Beispiel: '-' wird als 1.2-3 gerendert.

Hinzugefügt in Version 7.4.

Optionen für den Nitpicky-Modus¶

nitpicky¶

Typ:: bool
Standard:: False

Aktiviert den Nitpicky-Modus, wenn True. Im Nitpicky-Modus gibt Sphinx eine Warnung für alle Verweise aus, bei denen das Ziel nicht gefunden werden kann. Dies wird für neue Projekte empfohlen, da es sicherstellt, dass alle Verweise auf gültige Ziele gehen.

Sie können diesen Modus vorübergehend mit der Befehlszeilenoption --nitpicky aktivieren. Siehe nitpick_ignore für eine Möglichkeit, fehlende Verweise als „bekannt fehlend“ zu markieren.

nitpicky = True

Hinzugefügt in Version 1.0.

nitpick_ignore¶

Typ:: set[tuple[str, str]] | Sequence[tuple[str, str]]
Standard:: ()

Eine Menge oder Liste von Tupeln vom Typ (warning_type, target), die bei der Generierung von Warnungen im „Nitpicky-Modus“ ignoriert werden sollen. Beachten Sie, dass warning_type den Domainnamen enthalten sollte, falls vorhanden. Beispiel

nitpick_ignore = {
    ('py:func', 'int'),
    ('envvar', 'LD_LIBRARY_PATH'),
}

Hinzugefügt in Version 1.1.

Geändert in Version 6.2: Erlaubte Containertypen wurden zu set, list oder tuple geändert

nitpick_ignore_regex¶

Typ:: set[tuple[str, str]] | Sequence[tuple[str, str]]
Standard:: ()

Eine erweiterte Version von nitpick_ignore, die stattdessen die Zeichenketten warning_type und target als reguläre Ausdrücke interpretiert. Beachten Sie, dass der reguläre Ausdruck die gesamte Zeichenkette abgleichen muss (als wären die Marker ^ und $ eingefügt worden).

Zum Beispiel ignoriert (r'py:.*', r'foo.*bar\.B.*') Nitpicky-Warnungen für alle Python-Entitäten, die mit 'foo' beginnen und 'bar.B' enthalten, wie z. B. ('py:const', 'foo_package.bar.BAZ_VALUE') oder ('py:class', 'food.bar.Barman').

Hinzugefügt in Version 4.1.

Geändert in Version 6.2: Erlaubte Containertypen wurden zu set, list oder tuple geändert

Optionen für Objektsignaturen¶

add_function_parentheses¶

Typ:: bool
Standard:: True

Ein boolescher Wert, der bestimmt, ob Klammern an den Text von Funktions- und Methodenrollen angehängt werden (z. B. der Inhalt von :func:`input`), um anzuzeigen, dass der Name aufrufbar ist.

maximum_signature_line_length¶

Typ:: int | None
Standard:: None

Wenn die Länge einer Signatur in Zeichen die eingestellte Zahl überschreitet, wird jeder Parameter innerhalb der Signatur auf einer einzelnen logischen Zeile angezeigt.

Wenn None, gibt es keine maximale Länge und die gesamte Signatur wird auf einer einzigen logischen Zeile angezeigt.

Eine „logische Zeile“ ist ähnlich einem harten Zeilenumbruch – Builder oder Themes können eine einzelne logische Zeile „weich umbrechen“, und diese Einstellung hat keinen Einfluss auf dieses Verhalten.

Domains können Optionen bereitstellen, um hartes Umbrechen auf einer einzelnen Objekt-Direktive zu unterdrücken, wie es in den C-, C++- und Python-Domains zu sehen ist (z. B. py:function:single-line-parameter-list).

Hinzugefügt in Version 7.1.

strip_signature_backslash¶

Typ:: bool
Standard:: False

Wenn das Entfernen von Backslashes aktiviert ist, wird jede Vorkommnis von \\ in einer Domain-Direktive zu \ geändert, auch innerhalb von Zeichenkettenliteralen. Dies war das Verhalten vor Version 3.0, und das Setzen dieser Variablen auf True stellt dieses Verhalten wieder her.

Hinzugefügt in Version 3.0.

toc_object_entries¶

Typ:: bool
Standard:: True

Erstellt Einträge im Inhaltsverzeichnis für Domain-Objekte (z. B. Funktionen, Klassen, Attribute usw.).

Hinzugefügt in Version 5.2.

toc_object_entries_show_parents¶

Typ:: 'domain' | 'hide' | 'all'
Standard:: 'domain'

Eine Zeichenkette, die bestimmt, wie Domain-Objekte (Funktionen, Klassen, Attribute usw.) in ihrem Inhaltsverzeichnis-Eintrag angezeigt werden.

Verwenden Sie 'domain', damit die Domain die richtige Anzahl von übergeordneten Elementen anzeigen kann. Zum Beispiel würde die Python-Domain Class.method() und function() anzeigen und die module.-Ebene der Eltern weglassen.

Verwenden Sie 'hide', um nur den Namen des Elements ohne übergeordnete Elemente anzuzeigen (d. h. method()).

Verwenden Sie 'all', um den vollständig qualifizierten Namen des Objekts anzuzeigen (d. h. module.Class.method()) und alle übergeordneten Elemente anzuzeigen.

Hinzugefügt in Version 5.2.

Optionen für Quelldateien¶

exclude_patterns¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von Glob-Style-Mustern, die beim Suchen nach Quelldateien ausgeschlossen werden sollen. Sie werden mit den Quell-Dateinamen relativ zum Quellverzeichnis abgeglichen, wobei Schrägstriche als Verzeichnistrennzeichen auf allen Plattformen verwendet werden. exclude_patterns haben Vorrang vor include_patterns.

Beispielmuster

'library/xml.rst' – ignoriert die Datei library/xml.rst
'library/xml' – ignoriert das Verzeichnis library/xml
'library/xml*' – ignoriert alle Dateien und Verzeichnisse, die mit library/xml beginnen
'**/.git' – ignoriert alle .git-Verzeichnisse
'Thumbs.db' – ignoriert alle Thumbs.db-Dateien

exclude_patterns wird auch beim Suchen nach statischen Dateien in html_static_path und html_extra_path berücksichtigt.

Hinzugefügt in Version 1.0.

include_patterns¶

Typ:: Sequenz[str]
Standard:: ('**',)

Eine Liste von glob-style Mustern, die zum Finden von Quelldateien verwendet werden. Sie werden mit den Quelldateinamen relativ zum Quellverzeichnis abgeglichen, wobei Schrägstriche als Verzeichnistrenner auf allen Plattformen verwendet werden. Standardmäßig werden alle Dateien rekursiv aus dem Quellverzeichnis aufgenommen. exclude_patterns hat Vorrang vor include_patterns.

Beispielmuster

'**' – alle Dateien im Quellverzeichnis und dessen Unterverzeichnissen, rekursiv
'library/xml' – nur das Verzeichnis library/xml
'library/xml*' – alle Dateien und Verzeichnisse, die mit library/xml beginnen
'**/doc' – alle doc-Verzeichnisse (dies kann nützlich sein, wenn Dokumentation zusammen mit Quelldateien gespeichert ist)

Hinzugefügt in Version 5.1.

master_doc¶

root_doc¶

Typ:: str
Standard:: 'index'

Sphinx erstellt einen Dokumentenbaum basierend auf den toctree-Direktiven, die in den Quelldateien enthalten sind. Dies legt den Namen des Dokuments fest, das die Haupt-toctree-Direktive enthält, und somit die Wurzel des gesamten Baums. Beispiel

master_doc = 'contents'

Geändert in Version 2.0: Standard ist 'index' (zuvor 'contents').

Hinzugefügt in Version 4.0: Der Alias root_doc.

source_encoding¶

Typ:: str
Standard:: 'utf-8-sig'

Die Dateikodierung aller Quelldateien. Die empfohlene Kodierung ist 'utf-8-sig'.

Hinzugefügt in Version 0.5.

Veraltet seit Version 9.0: Die Unterstützung für Quellkodierungen, die von UTF-8 abweichen, ist veraltet. Sphinx 11 wird nur UTF-8-Dateien unterstützen.

source_suffix¶

Typ:: dict[str, str] | Sequence[str] | str
Standard:: {'.rst': 'restructuredtext'}

Ein Wörterbuch, das die Dateierweiterungen (Suffixe) von Quelldateien ihren Dateitypen zuordnet. Sphinx betrachtet alle Dateien mit Suffixen in source_suffix als Quelldateien. Beispiel

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

Standardmäßig unterstützt Sphinx nur den Dateityp 'restructuredtext'. Weitere Dateitypen können mit Erweiterungen hinzugefügt werden, die verschiedene Parser für Quelldateien registrieren, wie z. B. MyST-Parser. Lesen Sie die Dokumentation der Erweiterung, um zu erfahren, welche Dateitypen sie unterstützt.

Wenn der Wert eine Zeichenkette oder eine Sequenz von Zeichenketten ist, wird Sphinx davon ausgehen, dass es sich um 'restructuredtext'-Dateien handelt.

Hinweis

Dateierweiterungen müssen mit einem Punkt beginnen ('.').

Geändert in Version 1.3: Unterstützung für eine Liste von Dateierweiterungen.

Geändert in Version 1.8: Änderung zu einer Zuordnung von Dateierweiterungen zu Dateitypen.

Optionen für intelligente Anführungszeichen¶

smartquotes¶

Typ:: bool
Standard:: True

Wenn True, wird die Smart Quotes-Transformation verwendet, um Anführungszeichen und Bindestriche in typografisch korrekte Entitäten umzuwandeln.

Hinzugefügt in Version 1.6.6: Ersetzt das nun entfernte html_use_smartypants. Es wird standardmäßig auf alle Builder angewendet, außer man und text (siehe smartquotes_excludes.)

Hinweis

Eine docutils.conf-Datei im Konfigurationsverzeichnis (oder eine globale ~/.docutils-Datei) wird bedingungslos beachtet, wenn sie intelligente Anführungszeichen über die entsprechende Docutils-Option *deaktiviert*. Aber wenn sie sie *aktiviert*, hat smartquotes Vorrang.

smartquotes_action¶

Typ:: str
Standard:: 'qDe'

Anpassen der Smart Quotes-Transformation. Siehe unten für die zulässigen Codes. Das Standard-'qDe'-Format passt normale Anführungszeichen ", ', Dashs (gedankenstrich, Halbgeviertstrich) ---, -- und Ellipsen ... an.

'q': Anführungszeichen konvertieren
'b': Backtick-Anführungszeichen konvertieren (nur ``doppelt'')
'B': Backtick-Anführungszeichen konvertieren (sowohl ``doppelt'' als auch `einzeln')
'd': Bindestriche konvertieren (konvertiert -- in Gedankenstriche und --- in Halbgeviertstriche)
'D': Bindestriche konvertieren (alte Schule) (konvertiert -- in Halbgeviertstriche und --- in Gedankenstriche)
'i': Bindestriche konvertieren (invertierte alte Schule) (konvertiert -- in Gedankenstriche und --- in Halbgeviertstriche)
'e': Ellipsen konvertieren ...
'w': Konvertiert '"'-Entitäten in '"'

Hinzugefügt in Version 1.6.6.

smartquotes_excludes¶

Typ:: dict[str, list[str]]
Standard:: {'languages': ['ja'], 'builders': ['man', 'text']}

Steuert, wann die Smart Quotes-Transformation deaktiviert wird. Zulässige Schlüssel sind 'builders' und 'languages', und die Werte sind Listen von Zeichenketten.

Jeder Eintrag gibt eine hinreichende Bedingung an, um die Einstellung smartquotes zu ignorieren und die Smart Quotes-Transformation zu deaktivieren. Beispiel

smartquotes_excludes = {
    'languages': ['ja'],
    'builders': ['man', 'text'],
}

Hinweis

Derzeit wird bei der Ausführung von make mit mehreren Zielen nur das erste Ziel gegen den Eintrag 'builders' getestet und entscheidet für alle. Außerdem muss ein make text nach einem make html in der Form make text SPHINXOPTS="-E" ausgegeben werden, um eine Neuanalyse der Quelldateien zu erzwingen, da die zwischengespeicherten bereits transformiert sind. Auf der anderen Seite tritt das Problem bei der direkten Verwendung von sphinx-build nicht auf, da es (bei seiner Standardnutzung) die analysierten Quelldateien in Verzeichnissen pro Builder zwischenspeichert.

Hinweis

Eine alternative Methode, um intelligente Anführungszeichen für einen bestimmten Builder, z. B. latex, effektiv zu deaktivieren (oder anzupassen), ist die Verwendung von make auf diese Weise

make latex SPHINXOPTS="-D smartquotes_action="

Dies kann nach einem make html ohne Probleme erfolgen, im Gegensatz zur Situation aus dem vorherigen Hinweis.

Hinzugefügt in Version 1.6.6.

Optionen für Vorlagen¶

template_bridge¶

Typ:: str
Standard:: ''

Eine Zeichenkette mit dem vollständig qualifizierten Namen eines aufrufbaren Objekts (oder einfach einer Klasse), das eine Instanz von TemplateBridge zurückgibt. Diese Instanz wird dann zum Rendern von HTML-Dokumenten und möglicherweise der Ausgabe anderer Builder (derzeit des Change-Builders) verwendet. (Beachten Sie, dass die Template-Bridge themenbewusst gemacht werden muss, wenn HTML-Designs verwendet werden sollen.) Beispiel

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von Pfaden, die zusätzliche Vorlagen enthalten (oder Vorlagen, die integrierte/themespezifische Vorlagen überschreiben). Relative Pfade werden relativ zum Konfigurationsverzeichnis interpretiert. Beispiel

templates_path = ['.templates']

Geändert in Version 1.3: Da diese Dateien nicht kompiliert werden sollen, werden sie beim Entdecken von Quelldateien automatisch ausgeschlossen.

Optionen zur Warnungskontrolle¶

show_warning_types¶

Typ:: bool
Standard:: True

Fügt den Typ jeder Warnung als Suffix zur Warnmeldung hinzu. Zum Beispiel WARNUNG: [...] [index] oder WARNUNG: [...] [toc.circular]. Diese Einstellung kann nützlich sein, um zu bestimmen, welche Warnungstypen in eine suppress_warnings-Liste aufgenommen werden sollen.

Hinzugefügt in Version 7.3.0.

Geändert in Version 8.0.0: Der Standardwert ist jetzt True.

suppress_warnings¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von Warnungscodes, um beliebige Warnmeldungen zu unterdrücken.

Hinzugefügt in Version 1.4.

Standardmäßig unterstützt Sphinx die folgenden Warnungscodes

app.add_directive
app.add_generic_role
app.add_node
app.add_role
app.add_source_parser
config.cache
docutils
download.not_readable
duplicate_declaration.c
duplicate_declaration.cpp
epub.duplicated_toc_entry
epub.unknown_project_files
i18n.babel
i18n.inconsistent_references
i18n.not_readable
i18n.not_writeable
image.not_readable
index
misc.copy_overwrite
misc.highlighting_failure
ref.any
ref.citation
ref.doc
ref.equation
ref.footnote
ref.keyword
ref.numref
ref.option
ref.python
ref.ref
ref.term
source_code_parser.c
source_code_parser.cpp
toc.circular
toc.duplicate_entry
toc.empty_glob
toc.excluded
toc.no_title
toc.not_included
toc.not_readable
toc.secnum

Erweiterungen können auch eigene Warnungstypen definieren. Die von den erstklassigen sphinx.ext-Erweiterungen definierten sind:

autodoc
autodoc.import_object
autodoc.mocked_object
autosectionlabel.<document name>
autosummary
autosummary.import_cycle
duration
intersphinx.external

Sie können aus diesen Typen wählen. Sie können auch nur die erste Komponente angeben, um alle damit verbundenen Warnungen auszuschließen.

Hinzugefügt in Version 1.4: ref.citation, ref.doc, ref.keyword, ref.numref, ref.option, ref.ref und ref.term.

Hinzugefügt in Version 1.4.2: app.add_directive, app.add_generic_role, app.add_node, app.add_role und app.add_source_parser.

Hinzugefügt in Version 1.5: misc.highlighting_failure.

Hinzugefügt in Version 1.5.1: epub.unknown_project_files.

Hinzugefügt in Version 1.5.2: toc.secnum.

Hinzugefügt in Version 1.6: ref.footnote, download.not_readable und image.not_readable.

Hinzugefügt in Version 1.7: ref.python.

Hinzugefügt in Version 2.0: autodoc.import_object.

Hinzugefügt in Version 2.1: autosectionlabel.<document name>.

Hinzugefügt in Version 3.1: toc.circular.

Hinzugefügt in Version 3.3: epub.duplicated_toc_entry.

Hinzugefügt in Version 4.3: toc.excluded und toc.not_readable.

Hinzugefügt in Version 4.5: i18n.inconsistent_references.

Hinzugefügt in Version 7.1: index.

Hinzugefügt in Version 7.3: config.cache, intersphinx.external und toc.no_title.

Hinzugefügt in Version 7.4: docutils und autosummary.import_cycle.

Hinzugefügt in Version 8.0: misc.copy_overwrite.

Hinzugefügt in Version 8.2: autodoc.mocked_object, duplicate_declaration.c, duplicate_declaration.cpp, i18n.babel, i18n.not_readable, i18n.not_writeable, ref.any, toc.duplicate_entry, toc.empty_glob und toc.not_included.

Hinzugefügt in Version 9.0: duration.

Builder-Optionen¶

Optionen für die HTML-Ausgabe¶

Diese Optionen beeinflussen die HTML-Ausgabe. Verschiedene andere Builder leiten sich von der HTML-Ausgabe ab und nutzen ebenfalls diese Optionen.

html_theme¶

Typ:: str
Standard:: 'alabaster'

Das Thema für die HTML-Ausgabe. Siehe den Abschnitt HTML-Theming.

Hinzugefügt in Version 0.6.

Geändert in Version 1.3: Das Standardthema ist nun 'alabaster'.

html_theme_options¶

Typ:: dict[str, Any]
Standard:: {}

Ein Wörterbuch von Optionen, die das Aussehen des ausgewählten Themas beeinflussen. Diese sind themenspezifisch. Die von den integrierten Themen verstandenen Optionen werden hier beschrieben.

Hinzugefügt in Version 0.6.

html_theme_path¶

Typ:: list[str]
Standard:: []

Eine Liste von Pfaden, die benutzerdefinierte Themen enthalten, entweder als Unterverzeichnisse oder als ZIP-Dateien. Relative Pfade werden relativ zum Konfigurationsverzeichnis interpretiert.

Hinzugefügt in Version 0.6.

html_style¶

Typ:: Sequence[str] | str
Standard:: ()

Stylesheets, die für HTML-Seiten verwendet werden. Das vom ausgewählten Thema bereitgestellte Stylesheet wird standardmäßig verwendet. Eine Datei mit diesem Namen muss entweder im static/-Pfad von Sphinx oder in einem der benutzerdefinierten Pfade in html_static_path vorhanden sein. Wenn Sie nur einige Dinge vom Thema hinzufügen oder überschreiben möchten, verwenden Sie CSS @import, um das Stylesheet des Themas zu importieren.

Geändert in Version 5.1: Der Wert kann ein Iterable von Zeichenketten sein.

html_title¶

Typ:: str
Standard:: 'Projekt Version Dokumentation'

Der „Titel“ für HTML-Dokumente, die mit den eigenen Vorlagen von Sphinx generiert wurden. Dieser wird an das <title>-Tag einzelner Seiten angehängt und in der Navigationsleiste als „oberstes“ Element verwendet.

html_short_title¶

Typ:: str
Standard:: Der Wert von html_title

Ein kürzerer „Titel“ für HTML-Dokumente. Dieser wird für Links in der Kopfzeile und in der HTML-Hilfedokumentation verwendet.

Hinzugefügt in Version 0.4.

html_baseurl¶

Typ:: str
Standard:: ''

Die Basis-URL, die auf das Stammverzeichnis der HTML-Dokumentation verweist. Sie wird verwendet, um die Position des Dokuments mithilfe des Canonical Link Relation anzugeben.

Hinzugefügt in Version 1.8.

html_codeblock_linenos_style¶

Typ:: 'inline' | 'table'
Standard:: 'inline'

Der Stil der Zeilennummern für Codeblöcke.

'table': Zeilennummern mit dem <table>-Tag anzeigen
'inline': Zeilennummern mit dem <span>-Tag anzeigen

Hinzugefügt in Version 3.2.

Geändert in Version 4.0: Standard ist 'inline'.

Veraltet seit Version 4.0.

html_context¶

Typ:: dict[str, Any]
Standard:: {}

Ein Wörterbuch von Werten, die für alle Seiten an die Kontext-Engine übergeben werden. Einzelne Werte können auch über die --html-define Kommandozeilenoption von sphinx-build in dieses Wörterbuch eingefügt werden.

Hinzugefügt in Version 0.5.

html_logo¶

Typ:: str
Standard:: ''

Wenn angegeben, muss dies der Name einer Bilddatei sein (Pfad relativ zum Konfigurationsverzeichnis), die das Logo der Dokumentation darstellt, oder eine URL, die auf eine Bilddatei für das Logo verweist. Es wird am oberen Rand der Seitenleiste platziert; seine Breite sollte daher 200 Pixel nicht überschreiten.

Hinzugefügt in Version 0.4.1: Die Bilddatei wird in das Verzeichnis _static kopiert, aber nur, wenn die Datei dort noch nicht vorhanden ist.

Geändert in Version 4.0: Akzeptiert auch eine URL.

html_favicon¶

Typ:: str
Standard:: ''

Wenn angegeben, muss dies der Name einer Bilddatei sein (Pfad relativ zum Konfigurationsverzeichnis), die das Favicon der Dokumentation darstellt, oder eine URL, die auf eine Bilddatei für das Favicon verweist. Browser verwenden dies als Symbol für Tabs, Fenster und Lesezeichen. Es sollte ein 16x16 Pixel großes Icon im PNG-, SVG-, GIF- oder ICO-Format sein.

Beispiel

html_favicon = 'static/favicon.png'

Hinzugefügt in Version 0.4: Die Bilddatei wird in das Verzeichnis _static kopiert, aber nur, wenn die Datei dort noch nicht vorhanden ist.

Geändert in Version 4.0: Akzeptiert auch die URL für das Favicon.

html_css_files¶

Typ:: Sequence[str | tuple[str, dict[str, str]]]
Standard:: []

Eine Liste von CSS-Dateien. Der Eintrag muss eine Dateiname-Zeichenkette oder ein Tupel sein, das die Dateiname-Zeichenkette und das Attribute-Wörterbuch enthält. Der Dateiname muss relativ zum html_static_path oder eine vollständige URI mit Schema sein, wie 'https://example.org/style.css'. Das Attribute-Wörterbuch wird für die Attribute des <link>-Tags verwendet.

Beispiel

html_css_files = [
    'custom.css',
    'https://example.com/css/custom.css',
    ('print.css', {'media': 'print'}),
]

Das spezielle Attribut priority kann als ganze Zahl gesetzt werden, um die CSS-Datei in einem früheren oder späteren Schritt zu laden. Weitere Informationen finden Sie unter Sphinx.add_css_file().

Hinzugefügt in Version 1.8.

Geändert in Version 3.5: Unterstützt das priority-Attribut

html_js_files¶

Typ:: Sequence[str | tuple[str, dict[str, str]]]
Standard:: []

Eine Liste von JavaScript-Dateien. Der Eintrag muss eine Dateiname-Zeichenkette oder ein Tupel sein, das die Dateiname-Zeichenkette und das Attribute-Wörterbuch enthält. Der Dateiname muss relativ zum html_static_path oder eine vollständige URI mit Schema sein, wie 'https://example.org/script.js'. Das Attribute-Wörterbuch wird für die Attribute des <script>-Tags verwendet.

Beispiel

html_js_files = [
    'script.js',
    'https://example.com/scripts/custom.js',
    ('custom.js', {'async': 'async'}),
]

Als spezielles Attribut kann priority als ganze Zahl gesetzt werden, um die JavaScript-Datei in einem früheren oder späteren Schritt zu laden. Weitere Informationen finden Sie unter Sphinx.add_js_file().

Hinzugefügt in Version 1.8.

Geändert in Version 3.5: Unterstützt das priority-Attribut

html_static_path¶

Typ:: list[str]
Standard:: []

Eine Liste von Pfaden, die benutzerdefinierte statische Dateien (wie Stylesheets oder Skriptdateien) enthalten. Relative Pfade werden relativ zum Konfigurationsverzeichnis interpretiert. Sie werden nach den statischen Dateien des Themas in das _static-Verzeichnis der Ausgabe kopiert, sodass eine Datei namens default.css die default.css des Themas überschreibt.

Da diese Dateien nicht kompiliert werden sollen, werden sie automatisch von den Quelldateien ausgeschlossen.

Hinweis

Aus Sicherheitsgründen werden Dotfiles unter html_static_path nicht kopiert. Wenn Sie sie absichtlich kopieren möchten, fügen Sie jede Datei explizit zu dieser Einstellung hinzu

html_static_path = ['_static', '_static/.htaccess']

Ein alternativer Ansatz ist die Verwendung von html_extra_path, das das Kopieren von Dotfiles unter den Verzeichnissen ermöglicht.

Geändert in Version 0.4: Die Pfade in html_static_path können nun Unterverzeichnisse enthalten.

Geändert in Version 1.0: Die Einträge in html_static_path können nun einzelne Dateien sein.

Geändert in Version 1.8: Die Dateien unter html_static_path werden von den Quelldateien ausgeschlossen.

html_extra_path¶

Typ:: list[str]
Standard:: []

Eine Liste von Pfaden, die zusätzliche Dateien enthält, die nicht direkt mit der Dokumentation zusammenhängen, wie z. B. robots.txt oder .htaccess. Relative Pfade werden relativ zum Konfigurationsverzeichnis interpretiert. Sie werden in das Ausgabeverzeichnis kopiert. Sie überschreiben jede vorhandene Datei mit demselben Namen.

Da diese Dateien nicht kompiliert werden sollen, werden sie automatisch von den Quelldateien ausgeschlossen.

Hinzugefügt in Version 1.2.

Geändert in Version 1.4: Die Dotfiles im Verzeichnis `extra` werden in das Ausgabeverzeichnis kopiert. Und sie bezieht sich auf exclude_patterns beim Kopieren von zusätzlichen Dateien und Verzeichnissen und ignoriert, wenn der Pfad mit den Mustern übereinstimmt.

html_last_updated_fmt¶

Typ:: str
Standard:: None

Wenn gesetzt, wird ein Zeitstempel „Zuletzt aktualisiert am:“ in der Fußzeile der Seite eingefügt, unter Verwendung des gegebenen strftime()-Formats. Ein leerer String ist gleichbedeutend mit '%b %d, %Y' (oder einer lokalitätsabhängigen Entsprechung).

html_last_updated_use_utc¶

Typ:: bool
Standard:: False

Verwenden Sie GMT/UTC (+00:00) anstelle der lokalen Zeitzone des Systems für die an html_last_updated_fmt übergebene Zeit. Dies ist am nützlichsten, wenn das verwendete Format die Zeit enthält.

html_permalinks¶

Typ:: bool
Standard:: True

Fügt Link-Anker für jede Überschrift und jede Beschreibungs-Umgebung hinzu.

Hinzugefügt in Version 3.5.

html_permalinks_icon¶

Typ:: str
Standard:: '¶' (das Paragraphenzeichen)

Text für Link-Anker für jede Überschrift und jede Beschreibungs-Umgebung. HTML-Entitäten und Unicode sind erlaubt.

Hinzugefügt in Version 3.5.

html_sidebars¶

Typ:: dict[str, Sequence[str]]
Standard:: {}

Ein Wörterbuch, das benutzerdefinierte Sidebar-Vorlagen definiert und Dokumentnamen auf Vorlagennamen abbildet.

Die Schlüssel können glob-style Muster enthalten, in diesem Fall erhalten alle übereinstimmenden Dokumente die angegebenen Sidebars. (Eine Warnung wird ausgegeben, wenn mehr als ein glob-style Muster für ein Dokument zutrifft.)

Jeder Wert muss eine Liste von Strings sein, die die vollständige Liste der einzufügenden Sidebar-Vorlagen angibt. Wenn alle oder einige der Standard-Sidebars enthalten sein sollen, müssen diese ebenfalls in diese Liste aufgenommen werden.

Die Standard-Sidebars (für Dokumente, die keinem Muster entsprechen) werden vom Thema selbst definiert. Die eingebauten Themen verwenden standardmäßig diese Vorlagen: 'localtoc.html', 'relations.html', 'sourcelink.html' und 'searchbox.html'.

Die mitgelieferten First-Party-Sidebar-Vorlagen, die gerendert werden können, sind

localtoc.html – ein feingranularer Inhaltsverzeichnis des aktuellen Dokuments
globaltoc.html – ein grobgranulares Inhaltsverzeichnis für den gesamten Dokumentationssatz, eingeklappt
relations.html – zwei Links zum vorherigen und nächsten Dokument
sourcelink.html – ein Link zur Quelle des aktuellen Dokuments, wenn in html_show_sourcelink aktiviert
searchbox.html – das „Schnellsuche“-Feld

Beispiel

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windows-sidebar.html', 'searchbox.html'],
}

Dies rendert die benutzerdefinierte Vorlage windows-sidebar.html und die Schnellsuche im Sidebar des angegebenen Dokuments und rendert die Standard-Sidebars für alle anderen Seiten (mit der Ausnahme, dass das lokale TOC durch das globale TOC ersetzt wird).

Beachten Sie, dass dieser Wert nur dann keine Auswirkung hat, wenn das gewählte Thema keinen Sidebar besitzt, wie z.B. die eingebauten Themen **scrolls** und **haiku**.

Hinzugefügt in Version 1.0: Die Möglichkeit, glob-style Schlüssel zu verwenden und mehrere Sidebars anzugeben.

Veraltet seit Version 1.7: Ein einzelner String-Wert für html_sidebars wird entfernt.

Geändert in Version 2.0: html_sidebars muss eine Liste von Strings sein und akzeptiert keinen einzelnen String-Wert mehr.

html_additional_pages¶

Typ:: dict[str, str]
Standard:: {}

Zusätzliche Vorlagen, die als HTML-Seiten gerendert werden sollen. Muss ein Wörterbuch sein, das Dokumentnamen auf Vorlagennamen abbildet.

Beispiel

html_additional_pages = {
    'download': 'custom-download.html.jinja',
}

Dies rendert die Vorlage custom-download.html.jinja als Seite download.html.

html_domain_indices¶

Typ:: bool | Sequence[str]
Standard:: True

Wenn True, werden zusätzlich zum allgemeinen Index domänenspezifische Indizes generiert. Für z.B. die Python-Domäne ist dies der globale Modulindex.

Dieser Wert kann ein Boolean oder eine Liste von Indexnamen sein, die generiert werden sollen. Um den Indexnamen für einen bestimmten Index zu finden, schauen Sie auf den HTML-Dateinamen. Zum Beispiel hat der Python-Modulindex den Namen 'py-modindex'.

Beispiel

html_domain_indices = {
    'py-modindex',
}

Hinzugefügt in Version 1.0.

Geändert in Version 7.4: Erlaubt und bevorzugt einen Set-Typ.

html_use_index¶

Typ:: bool
Standard:: True

Steuert, ob ein Index zu den HTML-Dokumenten hinzugefügt wird.

Hinzugefügt in Version 0.4.

html_split_index¶

Typ:: bool
Standard:: False

Generiert zwei Versionen des Indexes: einmal als einzelne Seite mit allen Einträgen und einmal als eine Seite pro Anfangsbuchstabe.

Hinzugefügt in Version 0.4.

html_copy_source¶

Typ:: bool
Standard:: True

Wenn True, werden die reStructuredText-Quellen als _sources/docname in den HTML-Build aufgenommen.

html_show_sourcelink¶

Typ:: bool
Standard:: True

Wenn True (und html_copy_source ebenfalls True ist), werden Links zu den reStructuredText-Quellen zur Sidebar hinzugefügt.

Hinzugefügt in Version 0.6.

html_sourcelink_suffix¶

Typ:: str
Standard:: '.txt'

Das Suffix, das an Quellcode-Links angehängt wird (siehe html_show_sourcelink), es sei denn, die Dateien haben bereits dieses Suffix.

Hinzugefügt in Version 1.5.

html_use_opensearch¶

Typ:: str
Standard:: ''

Wenn nicht leer, wird eine OpenSearch-Beschreibungsdatei ausgegeben und alle Seiten enthalten einen <link>-Tag, der darauf verweist. Da OpenSearch keine relativen URLs für den Speicherort der Suchseite unterstützt, muss der Wert dieser Option die Basis-URL sein, von der diese Dokumente bereitgestellt werden (ohne abschließenden Schrägstrich), z.B. 'https://docs.pythonlang.de'.

Hinzugefügt in Version 0.2.

html_file_suffix¶

Typ:: str
Standard:: '.html'

Das Dateisuffix (Dateierweiterung) für generierte HTML-Dateien.

Hinzugefügt in Version 0.4.

html_link_suffix¶

Typ:: str
Standard:: Der Wert von **html_file_suffix**

Das Suffix für generierte Links zu HTML-Dateien. Gedacht zur Unterstützung esoterischerer Server-Setups.

Hinzugefügt in Version 0.6.

html_show_copyright¶

Typ:: bool
Standard:: True

Wenn True, wird „© Copyright …“ in der HTML-Fußzeile angezeigt, mit dem Wert oder den Werten aus copyright.

Hinzugefügt in Version 1.0.

html_show_search_summary¶

Typ:: bool
Standard:: True

Zeigt eine Zusammenfassung des Suchergebnisses an, d.h. den Text um das Schlüsselwort herum.

Hinzugefügt in Version 4.5.

html_show_sphinx¶

Typ:: bool
Standard:: True

Fügt „Erstellt mit Sphinx“ zur HTML-Fußzeile hinzu.

Hinzugefügt in Version 0.4.

html_output_encoding¶

Typ:: str
Standard:: 'utf-8'

Kodierung der HTML-Ausgabedateien. Dieser Kodierungsname muss sowohl ein gültiger Python-Kodierungsname als auch ein gültiger HTML-charset-Wert sein.

Hinzugefügt in Version 1.0.

html_compact_lists¶

Typ:: bool
Standard:: True

Wenn True, wird eine Liste, deren Elemente alle aus einem einzigen Absatz und/oder einer Unterliste bestehen, deren Elemente usw. (rekursive Definition), kein <p>-Element für eines ihrer Elemente verwenden. Dies ist das Standardverhalten von docutils. Standard: True.

Hinzugefügt in Version 1.0.

html_secnumber_suffix¶

Typ:: str
Standard:: '. '

Suffix für Abschnittsnummern in der HTML-Ausgabe. Auf ' ' setzen, um den letzten Punkt bei Abschnittsnummern zu unterdrücken.

Hinzugefügt in Version 1.0.

html_search_language¶

Typ:: str
Standard:: Der Wert von **language**

Sprache, die für die Generierung des HTML-Volltextsuchindex verwendet wird. Dies entspricht standardmäßig der globalen Sprache, die mit language ausgewählt wurde. Englisch ('en') wird als Fallback-Option verwendet, wenn keine Unterstützung für diese Sprache vorhanden ist.

Unterstützung besteht für die folgenden Sprachen

da – Dänisch
nl – Niederländisch
en – Englisch
fi – Finnisch
fr – Französisch
de – Deutsch
hu – Ungarisch
it – Italienisch
ja – Japanisch
no – Norwegisch
pt – Portugiesisch
ro – Rumänisch
ru – Russisch
es – Spanisch
sv – Schwedisch
tr – Türkisch
zh – Chinesisch

Tipp

Beschleunigung der Build-Geschwindigkeit

Jede Sprache (außer Japanisch) bietet ihren eigenen Stemming-Algorithmus. Sphinx verwendet standardmäßig eine Python-Implementierung. Wenn Sie die Erstellung der Indexdatei beschleunigen möchten, können Sie ein Drittanbieterpaket (PyStemmer) verwenden, indem Sie pip install PyStemmer ausführen.

Hinzugefügt in Version 1.1: Unterstützung für Englisch (en) und Japanisch (ja).

Geändert in Version 1.3: Zusätzliche Sprachen hinzugefügt.

html_search_options¶

Typ:: dict[str, str]
Standard:: {}

Ein Wörterbuch mit Optionen für die Sprachunterstützung der Suche. Die Bedeutung dieser Optionen hängt von der ausgewählten Sprache ab. Derzeit werden nur Japanisch und Chinesisch unterstützt.

Japanisch:

type – der Typ des zu verwendenden Splitters.

Die anderen Optionen hängen vom verwendeten Splitter ab.

'sphinx.search.ja.DefaultSplitter': Der TinySegmenter-Algorithmus, der standardmäßig verwendet wird.
'sphinx.search.ja.MecabSplitter':: Die MeCab-Bindung. Um diesen Splitter zu verwenden, wird die Python-Bindung „mecab“ oder eine dynamische Link-Bibliothek („libmecab.so“ für Linux, „libmecab.dll“ für Windows) benötigt.
'sphinx.search.ja.JanomeSplitter':: Die Janome-Bindung. Um diesen Splitter zu verwenden, ist Janome erforderlich.

Veraltet seit Version 1.6: 'mecab', 'janome' und 'default' sind veraltet. Zur Kompatibilität sind 'mecab', 'janome' und 'default' ebenfalls zulässig.

Optionen für 'mecab'

dic_enc:: dic_enc Option ist die Kodierung für den MeCab-Algorithmus.
dict:: dict Option ist das zu verwendende Wörterbuch für den MeCab-Algorithmus.
lib:: lib Option ist der Bibliotheksname zum Finden der MeCab-Bibliothek über ctypes, falls die Python-Bindung nicht installiert ist.

Zum Beispiel

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab .dic',
    'lib': '/path/to/libmecab.so',
}

Optionen für 'janome'

user_dic:: user_dic Option ist der Pfad zur Benutzerwörterbuchdatei für Janome.
user_dic_enc:: user_dic_enc Option ist die Kodierung für die vom user_dic Option angegebene Benutzerwörterbuchdatei. Standard ist „utf8“.

Chinesisch:

dict: Der jieba Wörterbuchpfad zur Verwendung eines benutzerdefinierten Wörterbuchs.

Hinzugefügt in Version 1.1.

Geändert in Version 1.4: Erlaubt jeden benutzerdefinierten Splitter in der type-Einstellung für Japanisch.

html_search_scorer¶

Typ:: str
Standard:: ''

Der Name einer JavaScript-Datei (relativ zum Konfigurationsverzeichnis), die einen Suchergebnis-Scorer implementiert. Wenn leer, wird die Standardeinstellung verwendet.

Der Scorer muss die folgende Schnittstelle implementieren und kann optional die Funktion score() für eine detailliertere Steuerung definieren.

const Scorer = {
    // Implement the following function to further tweak the score for each result
    score: result => {
      const [docName, title, anchor, descr, score, filename] = result

      // ... calculate a new score ...
      return score
    },

    // query matches the full name of an object
    objNameMatch: 11,
    // or matches in the last dotted part of the object name
    objPartialMatch: 6,
    // Additive scores depending on the priority of the object
    objPrio: {
      0: 15, // used to be importantResults
      1: 5, // used to be objectResults
      2: -5, // used to be unimportantResults
    },
    //  Used when the priority is not in the mapping.
    objPrioDefault: 0,

    // query found in title
    title: 15,
    partialTitle: 7,

    // query found in terms
    term: 5,
    partialTerm: 2,
};

Hinzugefügt in Version 1.2.

html_scaled_image_link¶

Typ:: bool
Standard:: True

Verlinkt Bilder, die mit einer Skalierungsoption (scale, width oder height) verkleinert wurden, zu ihrem ursprünglichen Bild in voller Auflösung. Dies überschreibt keine Verlinkung, die durch die target-Option auf der image-Direktive gegeben wurde, falls vorhanden.

Tipp

Um diese Funktion pro Bild zu deaktivieren, fügen Sie die Klasse no-scaled-link zur image-Direktive hinzu.

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

Hinzugefügt in Version 1.3.

Geändert in Version 3.0: Bilder mit der Klasse no-scaled-link werden nicht verlinkt.

html_math_renderer¶

Typ:: str
Standard:: 'mathjax'

Der zu verwendende Mathematik-Renderer für die HTML-Ausgabe. Die mitgelieferten Renderer sind *mathjax* und *imgmath*. Sie müssen auch die entsprechende Erweiterung in extensions laden.

Hinzugefügt in Version 1.8.

Optionen für die Single-HTML-Ausgabe¶

Diese Optionen beeinflussen die Single-HTML-Ausgabe. Dieser Builder leitet sich vom HTML-Builder ab, daher gelten die HTML-Optionen auch, wo immer sie angebracht sind.

singlehtml_sidebars¶

Typ:: dict[str, Sequence[str]]
Standard:: Der Wert von **html_sidebars**

Ein Wörterbuch, das benutzerdefinierte Sidebar-Vorlagen definiert und Dokumentnamen auf Vorlagennamen abbildet.

Dies hat den gleichen Effekt wie html_sidebars, aber der einzig zulässige Schlüssel ist 'index', und alle anderen Schlüssel werden ignoriert.

Optionen für die HTML-Hilfeausgabe¶

Diese Optionen beeinflussen die HTML-Hilfeausgabe. Dieser Builder leitet sich vom HTML-Builder ab, daher gelten die HTML-Optionen auch, wo immer sie angebracht sind.

htmlhelp_basename¶

Typ:: str
Standard:: '{project}doc'

Basisname der Ausgabedatei für den HTML-Hilfebuilder. Standard ist der Projektname mit entfernten Leerzeichen und angehängtem doc.

htmlhelp_file_suffix¶

Typ:: str
Standard:: '.html'

Dies ist das Dateisuffix für generierte HTML-Hilfedateien.

Hinzugefügt in Version 2.0.

htmlhelp_link_suffix¶

Typ:: str
Standard:: Der Wert von **htmlhelp_file_suffix**

Suffix für generierte Links zu HTML-Dateien.

Hinzugefügt in Version 2.0.

Optionen für die Apple-Hilfeausgabe¶

Hinzugefügt in Version 1.3.

Diese Optionen beeinflussen die Apple-Hilfeausgabe. Dieser Builder leitet sich vom HTML-Builder ab, daher gelten die HTML-Optionen auch, wo immer sie angebracht sind.

Hinweis

Die Apple-Hilfeausgabe funktioniert nur unter Mac OS X 10.6 und höher, da sie die Kommandozeilenwerkzeuge **hiutil** und **codesign** benötigt, von denen keines Open Source ist.

Sie können die Verwendung dieser Werkzeuge mit applehelp_disable_external_tools deaktivieren, aber das Ergebnis ist kein gültiges Hilfebuch, bis der Indexer über die .lproj-Verzeichnisse innerhalb des Pakets ausgeführt wird.

applehelp_bundle_name¶

Typ:: str
Standard:: Der Wert von **project**

Der Basisname für das Apple-Hilfebuch. Standard ist der Projektname mit entfernten Leerzeichen.

applehelp_bundle_id¶

Typ:: str
Standard:: None

Die Bundle-ID für das Hilfe-Bundle.

Warnung

Sie **müssen** diesen Wert festlegen, um Apple-Hilfe zu generieren.

applehelp_bundle_version¶

Typ:: str
Standard:: '1'

Die Bundle-Version als String.

applehelp_dev_region¶

Typ:: str
Standard:: 'en-us'

Die Entwicklungsregion. Standard ist Apples empfohlene Einstellung 'en-us'.

applehelp_icon¶

Typ:: str
Standard:: None

Pfad zur Symboldatei des Hilfe-Bundles oder None für kein Symbol. Laut Apples Dokumentation sollte dies eine 16x16 Pixel-Version des App-Symbols mit transparentem Hintergrund sein, als PNG-Datei gespeichert.

applehelp_kb_product¶

Typ:: str
Standard:: 'project-release'

Das Produkt-Tag für die Verwendung mit applehelp_kb_url.

applehelp_kb_url¶

Typ:: str
Standard:: None

Die URL für Ihren Knowledgebase-Server, z.B. https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. Zur Laufzeit ersetzt Help Viewer 'product' durch den Inhalt von applehelp_kb_product, 'query' durch den vom Benutzer in das Suchfeld eingegebenen Text und 'lang' durch die Systemsprache des Benutzers.

Setzen Sie dies auf None, um die Fernsuche zu deaktivieren.

applehelp_remote_url¶

Typ:: str
Standard:: None

Die URL für Remote-Inhalte. Sie können eine Kopie des Resources-Verzeichnisses Ihres Hilfebuchs an diesem Ort platzieren und Help Viewer wird versuchen, es zu verwenden, um aktualisierte Inhalte abzurufen.

Wenn Sie es beispielsweise auf https://example.com/help/Foo/ setzen und Help Viewer eine Kopie von index.html für einen englischsprachigen Kunden benötigt, sucht es unter https://example.com/help/Foo/en.lproj/index.html.

Setzen Sie dies auf None für keine Remote-Inhalte.

applehelp_index_anchors¶

Typ:: bool
Standard:: False

Weist den Hilfe-Indexer an, Anker in den generierten HTML-Dateien zu indexieren. Dies kann nützlich sein, um mit der Funktion AHLookupAnchor oder der Methode openHelpAnchor:inBook: in Ihrem Code zu einem bestimmten Thema zu springen. Es ermöglicht Ihnen auch, help:anchor-URLs zu verwenden. Weitere Informationen zu diesem Thema finden Sie in der Apple-Dokumentation.

applehelp_min_term_length¶

Typ:: str
Standard:: None

Steuert die minimale Begriffslänge für den Hilfe-Indexer. Wenn None, wird die Standardlänge verwendet.

applehelp_stopwords¶

Typ:: str
Standard:: Der Wert von **language**

Entweder eine Sprachspezifikation (um die integrierten Stoppwörter zu verwenden), der Pfad zu einer Stoppwort-Plist oder None, wenn Sie keine Stoppwörter verwenden möchten. Die Standard-Stoppwort-Plist befindet sich unter /usr/share/hiutil/Stopwords.plist und enthält zum Zeitpunkt der Erstellung Stoppwörter für die folgenden Sprachen

Deutsch (de)
Englisch (en)
Spanisch (es)
Französisch (fr)
Ungarisch (hu)
Italienisch (it)
Schwedisch (sv)

applehelp_locale¶

Typ:: str
Standard:: Der Wert von **language**

Gibt die Locale an, für die Hilfe generiert werden soll. Dies wird verwendet, um den Namen des .lproj-Verzeichnisses innerhalb der Resources des Hilfebuchs zu bestimmen und wird an den Hilfe-Indexer übergeben.

applehelp_title¶

Typ:: str
Standard:: 'project Help'

Gibt den Titel des Hilfebuchs an.

applehelp_codesign_identity¶

Typ:: str
Standard:: Der Wert von **CODE_SIGN_IDENTITY**

Gibt die zu verwendende Identität für die Code-Signatur an. Verwenden Sie None, wenn keine Code-Signatur durchgeführt werden soll.

Standardmäßig wird der Wert der Umgebungsvariable CODE_SIGN_IDENTITY verwendet, die von Xcode für Skript-Build-Phasen gesetzt wird, oder None, wenn diese Variable nicht gesetzt ist.

applehelp_codesign_flags¶

Typ:: list[str]
Standard:: Der Wert von **OTHER_CODE_SIGN_FLAGS**

Eine *Liste* von zusätzlichen Argumenten, die an codesign übergeben werden, wenn das Hilfebuch signiert wird.

Standardmäßig wird eine Liste basierend auf dem Wert der Umgebungsvariable OTHER_CODE_SIGN_FLAGS verwendet, die von Xcode für Skript-Build-Phasen gesetzt wird, oder eine leere Liste, wenn diese Variable nicht gesetzt ist.

applehelp_codesign_path¶

Typ:: str
Standard:: '/usr/bin/codesign'

Der Pfad zum codesign Programm.

applehelp_indexer_path¶

Typ:: str
Standard:: '/usr/bin/hiutil'

Der Pfad zum hiutil Programm.

applehelp_disable_external_tools¶

Typ:: bool
Standard:: False

Führt den Indexer oder das Code-Signierungswerkzeug nicht aus, unabhängig von anderen angegebenen Einstellungen.

Dies ist hauptsächlich für Testzwecke nützlich, oder wenn Sie den Sphinx-Build auf einer Nicht-macOS-Plattform ausführen und dann aus irgendeinem Grund die letzten Schritte auf einem Mac abschließen möchten.

Optionen für die EPUB-Ausgabe¶

Diese Optionen beeinflussen die EPUB-Ausgabe. Dieser Builder leitet sich vom HTML-Builder ab, daher gelten die HTML-Optionen auch, wo immer sie angebracht sind.

Hinweis

Der tatsächliche Wert für einige dieser Optionen ist nicht wichtig, aber sie sind für die Dublin Core Metadaten erforderlich.

epub_basename¶

Typ:: str
Standard:: Der Wert von **project**

Der Basisname für die EPUB-Datei.

epub_theme¶

Typ:: str
Standard:: 'epub'

Das HTML-Theme für die EPUB-Ausgabe. Da die Standard-Themes nicht für geringen Bildschirmplatz optimiert sind, ist es normalerweise nicht ratsam, dasselbe Theme für HTML- und EPUB-Ausgabe zu verwenden. Dies ist standardmäßig 'epub', ein Theme, das für die Platzersparnis entwickelt wurde.

epub_theme_options¶

Typ:: dict[str, Any]
Standard:: {}

Ein Wörterbuch von Optionen, die das Aussehen des ausgewählten Themas beeinflussen. Diese sind themenspezifisch. Die von den integrierten Themen verstandenen Optionen werden hier beschrieben.

Hinzugefügt in Version 1.2.

epub_title¶

Typ:: str
Standard:: Der Wert von **project**

Der Titel des Dokuments.

Geändert in Version 2.0: Standardmäßig ist dies die Option project (vorher html_title).

epub_description¶

Typ:: str
Standard:: 'unknown'

Die Beschreibung des Dokuments.

Hinzugefügt in Version 1.4.

Geändert in Version 1.5: Umbenannt von epub3_description

epub_author¶

Typ:: str
Standard:: Der Wert von **author**

Der Autor des Dokuments. Dies wird in die Dublin Core Metadaten eingetragen.

epub_contributor¶

Typ:: str
Standard:: 'unknown'

Der Name einer Person, Organisation usw., die eine sekundäre Rolle bei der Erstellung des Inhalts einer EPUB-Publikation gespielt hat.

Hinzugefügt in Version 1.4.

Geändert in Version 1.5: Umbenannt von epub3_contributor

epub_language¶

Typ:: str
Standard:: Der Wert von **language**

Die Sprache des Dokuments. Dies wird in die Dublin Core Metadaten eingetragen.

epub_publisher¶

Typ:: str
Standard:: Der Wert von **author**

Der Herausgeber des Dokuments. Dies wird in die Dublin Core Metadaten eingetragen. Sie können jeden sinnvollen String verwenden, z.B. die Projekt-Homepage.

epub_copyright¶

Typ:: str
Standard:: Der Wert von **copyright**

Das Copyright des Dokuments. Siehe copyright für zulässige Formate.

epub_identifier¶

Typ:: str
Standard:: 'unknown'

Eine Kennung für das Dokument. Dies wird in die Dublin Core Metadaten eingetragen. Bei veröffentlichten Dokumenten ist dies die ISBN-Nummer, aber Sie können auch ein alternatives Schema verwenden, z.B. die Projekt-Homepage.

epub_scheme¶

Typ:: str
Standard:: 'unknown'

Das Veröffentlichungsschema für die epub_identifier. Dies wird in die Dublin Core Metadaten eingetragen. Bei veröffentlichten Büchern ist das Schema 'ISBN'. Wenn Sie die Projekt-Homepage verwenden, scheint 'URL' sinnvoll.

epub_uid¶

Typ:: str
Standard:: 'unknown'

Eine eindeutige Kennung für das Dokument. Dies wird in den Dublin Core Metadaten hinterlegt. Sie können einen String im XML's Name-Format verwenden. Sie können Bindestriche, Punkte und Zahlen nicht als erstes Zeichen verwenden.

epub_cover¶

Typ:: tuple[str, str]
Standard:: ()

Die Informationen zur Titelseite. Dies ist ein Tupel, das die Dateinamen des Titellbildes und der HTML-Vorlage enthält. Die gerenderte HTML-Titelseite wird als erster Eintrag im Spine in content.opf eingefügt. Wenn der Vorlagen-Dateiname leer ist, wird keine HTML-Titelseite erstellt. Wenn das Tupel leer ist, wird überhaupt keine Titelseite erstellt.

Beispiele

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()

Hinzugefügt in Version 1.1.

epub_css_files¶

Typ:: Sequence[str | tuple[str, dict[str, str]]]
Standard:: []

Eine Liste von CSS-Dateien. Der Eintrag muss ein Dateiname-String oder ein Tupel sein, das den Dateiname-String und das Attribute-Dictionary enthält. Der Dateiname muss relativ zum html_static_path sein, oder eine vollständige URI mit Schema wie 'https://example.org/style.css'. Das Attribute-Dictionary wird für die Attribute des <link>-Tags verwendet. Weitere Informationen finden Sie unter html_css_files.

Hinzugefügt in Version 1.8.

epub_guide¶

Typ:: Sequence[tuple[str, str, str]]
Standard:: ()

Metadaten für das Guide-Element von content.opf. Dies ist eine Sequenz von Tupeln, die den Typ, die URI und den Titel der optionalen Guide-Informationen enthält. Details finden Sie in der OPF-Dokumentation. Wenn möglich, werden standardmäßig Einträge für die Typen cover und toc automatisch eingefügt. Die Typen können jedoch explizit überschrieben werden, wenn die Standardeinträge nicht geeignet sind.

Beispiel

epub_guide = (
    ('cover', 'cover.html', 'Cover Page'),
)

Der Standardwert ist ().

epub_pre_files¶

Typ:: Sequence[tuple[str, str]]
Standard:: ()

Zusätzliche Dateien, die vor dem von Sphinx generierten Text eingefügt werden sollen. Es ist eine Liste von Tupeln, die den Dateinamen und den Titel enthalten. Wenn der Titel leer ist, wird kein Eintrag zu toc.ncx hinzugefügt.

Beispiel

epub_pre_files = [
    ('index.html', 'Welcome'),
]

epub_post_files¶

Typ:: Sequence[tuple[str, str]]
Standard:: ()

Zusätzliche Dateien, die nach dem von Sphinx generierten Text eingefügt werden sollen. Es ist eine Liste von Tupeln, die den Dateinamen und den Titel enthalten. Diese Option kann verwendet werden, um einen Anhang hinzuzufügen. Wenn der Titel leer ist, wird kein Eintrag zu toc.ncx hinzugefügt.

Beispiel

epub_post_files = [
    ('appendix.xhtml', 'Appendix'),
]

epub_exclude_files¶

Typ:: Sequenz[str]
Standard:: []

Eine Sequenz von Dateien, die im Build-Verzeichnis generiert/kopiert werden, aber nicht in die EPUB-Datei aufgenommen werden sollen.

epub_tocdepth¶

Typ:: int
Standard:: 3

Die Tiefe des Inhaltsverzeichnisses in der Datei toc.ncx. Es sollte eine Ganzzahl größer als Null sein.

Tipp

Ein tief verschachteltes Inhaltsverzeichnis kann schwer zu navigieren sein.

epub_tocdup¶

Typ:: bool
Standard:: True

Dieses Flag bestimmt, ob ein Eintrag im Inhaltsverzeichnis am Anfang seiner verschachtelten Inhaltsverzeichnis-Liste erneut eingefügt wird. Dies ermöglicht eine einfachere Navigation zum Anfang eines Kapitels, kann aber verwirrend sein, da Einträge unterschiedlicher Tiefe in einer Liste vermischt werden.

epub_tocscope¶

Typ:: 'default' | 'includehidden'
Standard:: 'default'

Diese Einstellung steuert den Geltungsbereich des EPUB-Inhaltsverzeichnisses. Die Einstellung kann folgende Werte annehmen

'default': Alle nicht versteckten Einträge des Inhaltsverzeichnisses einschließen
'includehidden': Alle Einträge des Inhaltsverzeichnisses einschließen

Hinzugefügt in Version 1.2.

epub_fix_images¶

Typ:: bool
Standard:: False

Versuchen Sie, Bildformate zu reparieren, die von einigen EPUB-Readern nicht unterstützt werden. Derzeit werden Palettenbilder mit einer kleinen Farbtafel aufgewertet. Dies ist standardmäßig deaktiviert, da die automatische Konvertierung Informationen verlieren kann. Sie benötigen die Python Image Library (Pillow), um diese Option zu verwenden.

Hinzugefügt in Version 1.2.

epub_max_image_width¶

Typ:: int
Standard:: 0

Diese Option gibt die maximale Breite von Bildern an. Wenn sie auf einen Wert größer als Null gesetzt ist, werden Bilder mit einer größeren Breite als der angegebene Wert entsprechend skaliert. Wenn sie Null ist, erfolgt keine Skalierung. Sie benötigen die Python Image Library (Pillow), um diese Option zu verwenden.

Hinzugefügt in Version 1.2.

epub_show_urls¶

Typ:: 'footnote' | 'no' | 'inline'
Standard:: 'footnote'

Steuern Sie, wie URL-Adressen angezeigt werden. Dies ist sehr nützlich für Leser, die keine andere Möglichkeit haben, die verlinkte URL anzuzeigen. Die Einstellung kann folgende Werte annehmen

'inline': URLs inline in Klammern anzeigen.
'footnote': URLs in Fußnoten anzeigen.
'no': URLs nicht anzeigen.

Die Anzeige von Inline-URLs kann durch Hinzufügen von CSS-Regeln für die Klasse link-target angepasst werden.

Hinzugefügt in Version 1.2.

epub_use_index¶

Typ:: bool
Standard:: Der Wert von html_use_index

Ein Index zum EPUB-Dokument hinzufügen.

Hinzugefügt in Version 1.2.

epub_writing_mode¶

Typ:: 'horizontal' | 'vertical'
Standard:: 'horizontal'

Gibt die Schreibrichtung an. Es kann 'horizontal' und 'vertical' annehmen

`epub_writing_mode`	`'horizontal'`	`'vertical'`
writing-mode	`horizontal-tb`	`vertical-rl`
Seitenfluss	von links nach rechts	von rechts nach links
iBook's Scroll Theme Unterstützung	scroll-axis ist vertikal.	scroll-axis ist horizontal.

Optionen für LaTeX-Ausgabe¶

Diese Optionen beeinflussen die LaTeX-Ausgabe.

latex_engine¶

Typ:: 'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'
Standard:: 'pdflatex'

Die LaTeX-Engine zum Erstellen der Dokumentation. Die Einstellung kann folgende Werte annehmen

'pdflatex' – PDFLaTeX (Standard)
'xelatex' – XeLaTeX (Standard, wenn language eine der Werte el, zh_CN oder zh_TW ist)
'lualatex' – LuaLaTeX
'platex' – pLaTeX
'uplatex' – upLaTeX (Standard, wenn language 'ja' ist)

Wichtig

'pdflatex''s Unterstützung für Unicode-Zeichen ist begrenzt. Wenn Ihr Projekt Unicode-Zeichen verwendet, ist es oft einfacher, die Engine auf 'xelatex' oder 'lualatex' zu setzen und sicherzustellen, dass eine OpenType-Schriftart mit ausreichender Glyphenabdeckung verwendet wird, anstatt zu versuchen, 'pdflatex' mit zusätzlichen Unicode-Zeichen zum Laufen zu bringen. Seit Sphinx 2.0 ist die Standard-Schriftart GNU FreeFont, die eine gute Abdeckung von lateinischen, kyrillischen und griechischen Glyphen hat.

Hinweis

Sphinx 2.0 fügt Unterstützung für gelegentliche kyrillische und griechische Buchstaben oder Wörter in Dokumenten hinzu, die eine lateinische Sprache und 'pdflatex' verwenden. Um dies zu aktivieren, muss der Schlüssel 'fontenc' von latex_elements entsprechend verwendet werden.

Hinweis

Im Gegensatz zum MathJaX-Rendering für mathematische Ausdrücke in HTML-Ausgabe erfordert LaTeX zusätzliche Konfigurationen zur Unterstützung von Unicode-Literalen in der math-Direktive: die einzige umfassende Lösung (soweit wir wissen) ist die Verwendung von 'xelatex' oder 'lualatex' *und* das Hinzufügen von r'\usepackage{unicode-math}' (z. B. über den 'preamble'-Schlüssel von latex_elements). Möglicherweise bevorzugen Sie r'\usepackage[math-style=literal]{unicode-math}', um ein Unicode-Literal wie α (U+03B1) unverändert in der Ausgabe zu belassen, anstatt es als $\alpha$ zu rendern.

Geändert in Version 2.1.0: Verwende 'xelatex' (und das LaTeX-Paket xeCJK) standardmäßig für chinesische Dokumente.

Geändert in Version 2.2.1: Verwende 'xelatex' standardmäßig für griechische Dokumente.

Geändert in Version 2.3: Unterstützung für 'uplatex' hinzugefügt.

Geändert in Version 4.0: Verwende 'uplatex' standardmäßig für japanische Dokumente.

latex_documents¶

Typ:: Sequence[tuple[str, str, str, str, str, bool]]
Standard:: Die Standard-LaTeX-Dokumente

Dieser Wert bestimmt, wie der Dokumentenbaum in LaTeX-Quelldateien gruppiert wird. Es muss eine Liste von Tupeln sein (startdocname, targetname, title, author, theme, toctree_only), wobei die Elemente sind

startdocname: String, der den Dokumentennamen des Hauptdokuments der LaTeX-Datei angibt. Alle Dokumente, auf die vom startdoc-Dokument in ToC-Bäumen verwiesen wird, werden in die LaTeX-Datei aufgenommen. (Wenn Sie das Standard-Hauptdokument für Ihren LaTeX-Build verwenden möchten, geben Sie hier Ihr master_doc an.)
targetname: Dateiname der LaTeX-Datei im Ausgabeverzeichnis.
title: LaTeX-Dokumenttitel. Kann leer sein, um den Titel des startdoc-Dokuments zu verwenden. Dies wird als LaTeX-Markup eingefügt, sodass Sonderzeichen wie ein Backslash oder ein Ampersand durch die entsprechenden LaTeX-Befehle dargestellt werden müssen, wenn sie wörtlich eingefügt werden sollen.
autor: Autor für das LaTeX-Dokument. Das gleiche LaTeX-Markup-Vorbehalt wie für title gilt. Verwenden Sie \\and, um mehrere Autoren zu trennen, z. B.: 'John \\and Sarah' (Backslashes müssen Python-escaped werden, um LaTeX zu erreichen).
theme: LaTeX-Thema. Siehe latex_theme.
toctree_only: Muss True oder False sein. Wenn True, wird das startdoc-Dokument selbst nicht in die Ausgabe aufgenommen, sondern nur die Dokumente, auf die es über ToC-Bäume verweist. Mit dieser Option können Sie zusätzliche Inhalte im Hauptdokument unterbringen, die in HTML, aber nicht in der LaTeX-Ausgabe angezeigt werden.

Hinzugefügt in Version 0.3: Das 6. Element toctree_only. Tupel mit 5 Elementen werden weiterhin akzeptiert.

Hinzugefügt in Version 1.2: Früher war es erforderlich, den Dokumentklassennamen mit dem String "sphinx" zu präfixieren, wenn Ihre eigene Dokumentenklasse eingeschlossen wurde. Dies ist nicht mehr notwendig.

latex_logo¶

Typ:: str
Standard:: ''

Wenn angegeben, muss dies der Name einer Bilddatei sein (Pfad relativ zum Konfigurationsverzeichnis), die das Logo der Dokumentation ist. Sie wird oben auf der Titelseite platziert.

latex_toplevel_sectioning¶

Typ:: 'part' | 'chapter' | 'section'
Standard:: None

Dieser Wert bestimmt die oberste Gliederungseinheit. Die Standardeinstellung ist 'section', wenn latex_theme 'howto' ist, und 'chapter', wenn es 'manual' ist. Die Alternative ist in beiden Fällen 'part' anzugeben, was bedeutet, dass das LaTeX-Dokument den Befehl \part verwendet.

In diesem Fall gerät die Nummerierung der Gliederungseinheiten auf der nächsten Ebene aus dem Takt mit der HTML-Nummerierung, da LaTeX standardmäßig die Nummerierung von \chapter (oder \section für das 'howto'-Theme) nicht zurücksetzt, wenn es auf einen \part-Befehl stößt.

Hinzugefügt in Version 1.4.

latex_appendices¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von Dokumentennamen, die als Anhang an alle Handbücher angehängt werden sollen. Dies wird ignoriert, wenn latex_theme auf 'howto' gesetzt ist.

latex_domain_indices¶

Typ:: bool | Sequence[str]
Standard:: True

Wenn True, werden zusätzlich zum allgemeinen Index domänenspezifische Indizes generiert. Für z.B. die Python-Domäne ist dies der globale Modulindex.

Dieser Wert kann ein Boolean oder eine Liste von Indexnamen sein, die generiert werden sollen. Um den Indexnamen für einen bestimmten Index zu finden, schauen Sie auf den HTML-Dateinamen. Zum Beispiel hat der Python-Modulindex den Namen 'py-modindex'.

Beispiel

latex_domain_indices = {
    'py-modindex',
}

Hinzugefügt in Version 1.0.

Geändert in Version 7.4: Erlaubt und bevorzugt einen Set-Typ.

latex_show_pagerefs¶

Typ:: bool
Standard:: False

Seitenzahlreferenzen nach internen Verweisen hinzufügen. Dies ist sehr nützlich für gedruckte Exemplare des Handbuchs.

Hinzugefügt in Version 1.0.

latex_show_urls¶

Typ:: 'no' | 'footnote' | 'inline'
Standard:: 'no'

Steuern Sie, wie URL-Adressen angezeigt werden. Dies ist sehr nützlich für gedruckte Exemplare des Handbuchs. Die Einstellung kann folgende Werte annehmen

'no': URLs nicht anzeigen
'footnote': URLs in Fußnoten anzeigen
'inline': URLs inline in Klammern anzeigen

Hinzugefügt in Version 1.0.

Geändert in Version 1.1: Dieser Wert ist jetzt ein String; zuvor war er ein boolescher Wert, und ein wahrer Wert wählte die 'inline' Anzeige. Aus Kompatibilitätsgründen wird True weiterhin akzeptiert.

latex_use_latex_multicolumn¶

Typ:: bool
Standard:: False

Verwenden Sie das Standard-LaTeX-Kommando \multicolumn für zusammengeführte Zellen in Tabellen.

False: Sphinx' eigene Makros werden für zusammengeführte Zellen aus Gittertabellen verwendet. Sie erlauben allgemeine Inhalte (Literalblöcke, Listen, Blockquotes usw.), können aber Probleme haben, wenn die Direktive tabularcolumns verwendet wurde, um LaTeX-Markup des Typs >{..}, <{..}, @{..} als Spaltenspezifikation einzufügen.
True: Verwenden Sie das Standard-LaTeX-Kommando \multicolumn; dies ist inkompatibel mit Literalblöcken in horizontal zusammengeführten Zellen und auch mit mehreren Absätzen in solchen Zellen, wenn die Tabelle mit tabulary gerendert wird.

Hinzugefügt in Version 1.6.

latex_table_style¶

Typ:: list[str]
Standard:: ['booktabs', 'colorrows']

Eine Liste von Stilklassen (Strings). Derzeit unterstützt

'booktabs': Keine vertikalen Linien und nur 2 oder 3 horizontale Linien (letztere, wenn ein Header vorhanden ist), unter Verwendung des Pakets booktabs.
'borderless': Überhaupt keine Linien.
'colorrows': Die Tabellenzeilen werden mit abwechselnden Hintergrundfarben gerendert. Die Schnittstelle zur Anpassung ist über dedizierte Schlüssel von Der sphinxsetup-Konfigurationseinstellung.

Wichtig

Mit dem Stil 'colorrows' wird der LaTeX-Befehl \rowcolors zu einer No-Op (dieser Befehl hat Einschränkungen und hat nie alle Arten von Tabellen, die Sphinx in LaTeX erzeugt, korrekt unterstützt). Bitte verwenden Sie stattdessen die Konfigurationsschlüssel für LaTeX-Tabellenfarben.

Um die Stile für eine Tabelle anzupassen, verwenden Sie die Option :class:, wenn die Tabelle mit einer Direktive definiert ist, oder fügen Sie andernfalls eine rst-class-Direktive vor der Tabelle ein (siehe Tabellen).

Derzeit erkannte Klassen sind booktabs, borderless, standard, colorrows, nocolorrows. Die letzteren beiden können mit jeder der ersten drei kombiniert werden. Die Klasse standard erzeugt Tabellen mit horizontalen und vertikalen Linien (wie es vor Sphinx 6.0.0 Standard war).

Eine einzeilige, mehrspaltige zusammengeführte Zelle folgt der Zeilenfarbe, wenn diese gesetzt ist. Siehe auch TableMergeColor{Header,Odd,Even} im Abschnitt Die sphinxsetup-Konfigurationseinstellung.

Hinweis

Es ist in LaTeX fest kodiert, dass eine einzelne Zelle die Zeilenfarbe befolgt, auch wenn eine Spaltenfarbe über \columncolor aus einer Spaltenspezifikation gesetzt ist (siehe tabularcolumns). Sphinx bietet \sphinxnorowcolor, das in einer Tabellenspalten-Spezifikation wie folgt verwendet werden kann
```
>{\columncolor{blue}\sphinxnorowcolor}
```
Sphinx bietet auch \sphinxcolorblend, das jedoch das Paket xcolor benötigt. Hier ist ein Beispiel
```
>{\sphinxcolorblend{!95!red}}
```
Das bedeutet, dass in dieser Spalte die Zeilenfarben leicht mit Rot getönt werden; siehe die Dokumentation von xcolor für mehr über die Syntax seines \blendcolors-Befehls (ein \blendcolors anstelle von \sphinxcolorblend würde die Farben des Zellinhalts ändern, nicht die des Zell-Hintergrunds). Ein Anwendungsbeispiel finden Sie im Abschnitt Veraltete APIs dieses Dokuments im PDF-Format.

Hinweis

Wenn Sie eine spezielle Farbe für den *Inhalt* der Zellen einer bestimmten Spalte verwenden möchten, verwenden Sie >{\noindent\color{<color>}}, möglicherweise zusätzlich zu den obigen.
Mehrzeilige zusammengeführte Zellen, ob einspaltig oder mehrspaltig, ignorieren derzeit jede gesetzte Spalten-, Zeilen- oder Zellfarbe.
Es ist möglich, für eine einfache Zelle eine benutzerdefinierte Farbe über die Direktive raw und den LaTeX-Befehl \cellcolor festzulegen, der irgendwo im Zellinhalt verwendet wird. Dies hat derzeit keine Auswirkung in einer zusammengeführten Zelle, unabhängig von ihrer Art.

Hinweis

In einem Dokument, das 'booktabs' nicht global verwendet, ist es möglich, eine einzelne Tabelle über die Klasse booktabs zu gestalten, aber es muss r'\usepackage{booktabs}' zum LaTeX-Präambel hinzugefügt werden.

Andererseits kann man die Klasse colorrows für einzelne Tabellen ohne zusätzliche Pakete verwenden (da Sphinx seit 5.3.0 immer colortbl lädt).

Hinzugefügt in Version 5.3.0.

Geändert in Version 6.0.0: Standard von [] auf ['booktabs', 'colorrows'] geändert.

latex_use_xindy¶

Typ:: bool
Standard:: True, wenn latex_engine in {'xelatex', 'lualatex'} sonst False

Verwenden Sie Xindy zur Vorbereitung des Index für allgemeine Begriffe. Standardmäßig verwendet der LaTeX-Builder makeindex zur Vorbereitung des Index für allgemeine Begriffe. Die Verwendung von Xindy bedeutet, dass Wörter mit UTF-8-Zeichen für die language korrekt sortiert werden.

Diese Option wird ignoriert, wenn latex_engine 'platex' (japanische Dokumente; mendex ersetzt dann makeindex) ist.
Der Standardwert ist True für 'xelatex' oder 'lualatex', da makeindex .ind-Dateien erstellt, die ungültige Bytes für die UTF-8-Kodierung enthalten, wenn ein indizierter Begriff mit einem Nicht-ASCII-Zeichen beginnt. Mit 'lualatex' bricht dies dann den PDF-Build ab.
Der Standardwert ist False für 'pdflatex', aber True wird für nicht-englische Dokumente empfohlen, sobald einige indizierte Begriffe Nicht-ASCII-Zeichen aus dem Schriftsystem der Sprache verwenden. Der Versuch, einen Begriff zu indizieren, dessen erstes Zeichen nicht-ASCII ist, wird den Build abbrechen, wenn latex_use_xindy auf seinem Standardwert False belassen wird.

Sphinx fügt der xindy-Basisdistribution einige spezielle Unterstützung für die Verwendung der 'pdflatex'-Engine mit kyrillischen Schriftsystemen hinzu. Sowohl mit 'pdflatex' als auch mit Unicode-Engines verarbeiten kyrillische Dokumente die Indizierung lateinischer Namen korrekt, auch solche mit diakritischen Zeichen.

Hinzugefügt in Version 1.8.

latex_elements¶

Typ:: dict[str, str]
Standard:: {}

Hinzugefügt in Version 0.5.

Siehe die vollständige Dokumentation für latex_elements.

latex_docclass¶

Typ:: dict[str, str]
Standard:: {}

Ein Dictionary, das 'howto' und 'manual' auf Namen tatsächlicher Dokumentenklassen abbildet, die als Basis für die beiden Sphinx-Klassen verwendet werden. Standardmäßig wird 'article' für 'howto' und 'report' für 'manual' verwendet.

Hinzugefügt in Version 1.0.

Geändert in Version 1.5: In japanischer Dokumentation (language ist 'ja') werden standardmäßig 'jreport' für 'howto' und 'jsbook' für 'manual' verwendet.

latex_additional_files¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von Dateinamen, relativ zum Konfigurationsverzeichnis, die in das Build-Verzeichnis kopiert werden sollen, wenn die LaTeX-Ausgabe erstellt wird. Dies ist nützlich, um Dateien zu kopieren, die Sphinx nicht automatisch kopiert, oder um Sphinx-LaTeX-Supportdateien mit benutzerdefinierten Versionen zu überschreiben. Bilddateien, auf die in Quelldateien verwiesen wird (z. B. über .. image::), werden automatisch kopiert und sollten dort nicht aufgeführt werden.

Achtung

Dateinamen mit der Erweiterung .tex werden automatisch an den PDF-Build-Prozess übergeben, der durch sphinx-build -M latexpdf oder durch make latexpdf ausgelöst wird. Wenn die Datei nur hinzugefügt wurde, um von einer geänderten Präambel aus \input{} zu werden, müssen Sie einen weiteren Suffix wie .txt an den Dateinamen anhängen und das Makro \input{} entsprechend anpassen.

Hinzugefügt in Version 0.6.

Geändert in Version 1.2: Dies überschreibt die von Sphinx bereitgestellten Dateien wie z. B. sphinx.sty.

latex_theme¶

Typ:: str
Standard:: 'manual'

Das "Thema", das die LaTeX-Ausgabe verwenden soll. Es ist eine Sammlung von Einstellungen für die LaTeX-Ausgabe (z. B. Dokumentenklasse, oberste Gliederungseinheit usw.).

Die mitgelieferten LaTeX-Themes sind manual und howto.

manual: Ein LaTeX-Theme zum Schreiben eines Handbuchs. Es importiert die Dokumentenklasse report (japanische Dokumente verwenden jsbook).
howto: Ein LaTeX-Theme zum Schreiben eines Artikels. Es importiert die Dokumentenklasse article (japanische Dokumente verwenden jreport). latex_appendices ist nur für dieses Theme verfügbar.

Hinzugefügt in Version 3.0.

latex_theme_options¶

Typ:: dict[str, Any]
Standard:: {}

Ein Wörterbuch von Optionen, die das Aussehen und Verhalten des ausgewählten Themes beeinflussen. Diese sind themenspezifisch.

Hinzugefügt in Version 3.1.

latex_theme_path¶

Typ:: list[str]
Standard:: []

Eine Liste von Pfaden, die benutzerdefinierte LaTeX-Themes als Unterverzeichnisse enthalten. Relative Pfade werden relativ zum Konfigurationsverzeichnis interpretiert.

Hinzugefügt in Version 3.0.

Optionen für die Textausgabe¶

Diese Optionen beeinflussen die Textausgabe.

text_add_secnumbers¶

Typ:: bool
Standard:: True

Fügt Abschnittsnummern in die Textausgabe ein.

Hinzugefügt in Version 1.7.

text_newlines¶

Typ:: 'unix' | 'windows' | 'native'
Standard:: 'unix'

Legt fest, welche Zeilenendezeichen in der Textausgabe verwendet werden.

'unix': Verwendet Zeilenenden im Unix-Stil (\n).
'windows': Verwendet Zeilenenden im Windows-Stil (\r\n).
'native': Verwendet den Zeilenendungsstil der Plattform, auf der die Dokumentation erstellt wird.

Hinzugefügt in Version 1.1.

text_secnumber_suffix¶

Typ:: str
Standard:: '. '

Suffix für Abschnittsnummern in der Textausgabe. Setzen Sie auf ' ', um den abschließenden Punkt bei Abschnittsnummern zu unterdrücken.

Hinzugefügt in Version 1.7.

text_sectionchars¶

Typ:: str
Standard:: '*=-~"+`'

Eine Zeichenkette aus 7 Zeichen, die zum Unterstreichen von Abschnitten verwendet werden sollen. Das erste Zeichen wird für Überschriften erster Ebene, das zweite für Überschriften zweiter Ebene usw. verwendet.

Hinzugefügt in Version 1.1.

Optionen für die Handbuchseiten-Ausgabe¶

Diese Optionen beeinflussen die Ausgabe von Handbuchseiten.

man_pages¶

Typ:: Sequenz[tuple[str, str, str, str, str]]
Standard:: Die Standard-Handbuchseiten

Dieser Wert bestimmt, wie der Dokumentenbaum in Handbuchseiten gruppiert wird. Es muss sich um eine Liste von Tupeln handeln (startdocname, name, description, authors, section), wobei die Elemente

startdocname: Zeichenkette, die den Dokumentennamen des Hauptdokuments der Handbuchseite angibt. Alle Dokumente, auf die im Inhaltsverzeichnisbaum vom startdoc verwiesen wird, werden in die Handbuchseite aufgenommen. (Wenn Sie das Standard-Hauptdokument für Ihren Handbuchseiten-Build verwenden möchten, geben Sie hier Ihr master_doc an.)
name: Name der Handbuchseite. Dies sollte eine kurze Zeichenkette ohne Leerzeichen oder Sonderzeichen sein. Sie wird zur Bestimmung des Dateinamens sowie des Namens der Handbuchseite (im Abschnitt NAME) verwendet.
description: Beschreibung der Handbuchseite. Dies wird im Abschnitt NAME verwendet. Kann eine leere Zeichenkette sein, wenn Sie den Abschnitt NAME nicht automatisch generieren möchten.
authors: Eine Liste von Zeichenketten mit Autoren oder eine einzelne Zeichenkette. Kann eine leere Zeichenkette oder Liste sein, wenn Sie nicht möchten, dass ein AUTHORS-Abschnitt in der Handbuchseite automatisch generiert wird.
section: Der Abschnitt der Handbuchseite. Wird für den Ausgabedateinamen sowie in der Kopfzeile der Handbuchseite verwendet.

Hinzugefügt in Version 1.0.

man_show_urls¶

Typ:: bool
Standard:: False

Fügt URL-Adressen nach Links hinzu.

Hinzugefügt in Version 1.1.

man_make_section_directory¶

Typ:: bool
Standard:: True

Erstellt ein Abschnittsverzeichnis beim Erstellen von Handbuchseiten.

Hinzugefügt in Version 3.3.

Geändert in Version 4.0: Der Standardwert ist jetzt False (zuvor True).

Geändert in Version 4.0.2: Die Änderung des Standardwerts wurde rückgängig gemacht.

Optionen für die Texinfo-Ausgabe¶

Diese Optionen beeinflussen die Texinfo-Ausgabe.

texinfo_documents¶

Typ:: Sequenz[tuple[str, str, str, str, str, str, str, bool]]
Standard:: Die Standard-Texinfo-Dokumente

Dieser Wert bestimmt, wie der Dokumentenbaum in Texinfo-Quelldateien gruppiert wird. Es muss sich um eine Liste von Tupeln handeln (startdocname, targetname, title, author, dir_entry, description, category, toctree_only), wobei die Elemente

startdocname: Zeichenkette, die den Dokumentennamen des Hauptdokuments der Texinfo-Datei angibt. Alle Dokumente, auf die im Inhaltsverzeichnisbaum vom startdoc verwiesen wird, werden in die Texinfo-Datei aufgenommen. (Wenn Sie das Standard-Hauptdokument für Ihren Texinfo-Build verwenden möchten, geben Sie hier Ihr master_doc an.)
targetname: Dateiname (ohne Erweiterung) der Texinfo-Datei im Ausgabeverzeichnis.
title: Texinfo-Dokumenttitel. Kann leer sein, um den Titel des startdoc-Dokuments zu verwenden. Wird als Texinfo-Markup eingefügt, sodass Sonderzeichen wie @ und {} maskiert werden müssen, um sie wörtlich einzufügen.
autor: Autor für das Texinfo-Dokument. Wird als Texinfo-Markup eingefügt. Verwenden Sie @*, um mehrere Autoren zu trennen, z. B.: 'John@*Sarah'.
dir_entry: Der Name, der in der DIR-Menüdatei der obersten Ebene angezeigt wird.
description: Beschreibender Text, der in der DIR-Menüdatei der obersten Ebene angezeigt wird.
category: Gibt den Abschnitt an, in dem dieser Eintrag in der DIR-Menüdatei der obersten Ebene angezeigt wird.
toctree_only: Muss True oder False sein. Wenn True, ist das startdoc-Dokument selbst nicht in der Ausgabe enthalten, nur die Dokumente, auf die über Inhaltsverzeichnisbäume verwiesen wird. Mit dieser Option können Sie zusätzliche Elemente im Hauptdokument platzieren, die in HTML angezeigt werden, aber nicht in der Texinfo-Ausgabe.

Hinzugefügt in Version 1.1.

texinfo_appendices¶

Typ:: Sequenz[str]
Standard:: []

Eine Liste von Dokumentennamen, die als Anhang an alle Handbücher angehängt werden sollen.

Hinzugefügt in Version 1.1.

texinfo_cross_references¶

Typ:: bool
Standard:: True

Generiert Inline-Referenzen in einem Dokument. Das Deaktivieren von Inline-Referenzen kann eine Info-Datei mit einem eigenständigen Leser (info) lesbarer machen.

Hinzugefügt in Version 4.4.

texinfo_domain_indices¶

Typ:: bool | Sequence[str]
Standard:: True

Wenn True, werden zusätzlich zum allgemeinen Index domänenspezifische Indizes generiert. Für z.B. die Python-Domäne ist dies der globale Modulindex.

Dieser Wert kann ein Boolean oder eine Liste von Indexnamen sein, die generiert werden sollen. Um den Indexnamen für einen bestimmten Index zu finden, schauen Sie auf den HTML-Dateinamen. Zum Beispiel hat der Python-Modulindex den Namen 'py-modindex'.

Beispiel

texinfo_domain_indices = {
    'py-modindex',
}

Hinzugefügt in Version 1.1.

Geändert in Version 7.4: Erlaubt und bevorzugt einen Set-Typ.

texinfo_elements¶

Typ:: dict[str, Any]
Standard:: {}

Ein Wörterbuch, das Texinfo-Schnipsel enthält, die diejenigen überschreiben, die Sphinx normalerweise in die generierten .texi-Dateien einfügt.

Zu überschreibende Schlüssel sind:

'paragraphindent'
Anzahl der Leerzeichen zum Einrücken der ersten Zeile jedes Absatzes, Standard ist 2. Geben Sie 0 für keine Einrückung an.

'exampleindent'
Anzahl der Leerzeichen zum Einrücken der Zeilen für Beispiele oder wörtliche Blöcke, Standard ist 4. Geben Sie 0 für keine Einrückung an.

'preamble'
Texinfo-Markup, das am Anfang der Datei eingefügt wird.

'copying'
Texinfo-Markup, das in den @copying-Block eingefügt und nach dem Titel angezeigt wird. Der Standardwert besteht aus einer einfachen Titelseite, die das Projekt identifiziert.
Schlüssel, die von anderen Optionen gesetzt werden und daher nicht überschrieben werden sollten, sind 'author', 'body', 'date', 'direntry', 'filename', 'project', 'release' und 'title'.

Hinzugefügt in Version 1.1.

texinfo_no_detailmenu¶

Typ:: bool
Standard:: False

Generiert keine @detailmenu im Menü des „Top“-Knotens, das Einträge für jeden Unterknoten im Dokument enthält.

Hinzugefügt in Version 1.2.

texinfo_show_urls¶

Typ:: 'footnote' | 'no' | 'inline'
Standard:: 'footnote'

Steuert, wie URL-Adressen angezeigt werden. Die Einstellung kann folgende Werte haben:

'footnote': URLs in Fußnoten anzeigen.
'no': URLs nicht anzeigen.
'inline': URLs inline in Klammern anzeigen.

Hinzugefügt in Version 1.1.

Optionen für die QtHelp-Ausgabe¶

Diese Optionen beeinflussen die QtHelp-Ausgabe. Dieser Builder leitet sich vom HTML-Builder ab, sodass die HTML-Optionen ebenfalls dort angewendet werden, wo sie relevant sind.

qthelp_basename¶

Typ:: str
Standard:: Der Wert von **project**

Der Basisname für die QtHelp-Datei.

qthelp_namespace¶

Typ:: str
Standard:: 'org.sphinx.{project_name}.{project_version}'

Der Namespace für die QtHelp-Datei.

qthelp_theme¶

Typ:: str
Standard:: 'nonav'

Das HTML-Theme für die QtHelp-Ausgabe.

qthelp_theme_options¶

Typ:: dict[str, Any]
Standard:: {}

Ein Wörterbuch von Optionen, die das Aussehen des ausgewählten Themas beeinflussen. Diese sind themenspezifisch. Die von den integrierten Themen verstandenen Optionen werden hier beschrieben.

Optionen für die XML-Ausgabe¶

xml_pretty¶

Typ:: bool
Standard:: True

Formatiert die XML-Ausgabe leserlich.

Hinzugefügt in Version 1.2.

Optionen für den linkcheck-Builder¶

Filterung¶

Diese Optionen steuern, welche Links der linkcheck-Builder überprüft und welche Fehler und Weiterleitungen er ignoriert.

linkcheck_allowed_redirects¶

Typ:: dict[str, str]

Ein Wörterbuch, das ein Muster der Quell-URI einer Muster der kanonischen URI zuordnet. Der linkcheck-Builder behandelt den weitergeleiteten Link als „funktionierend“, wenn

der Link im Dokument mit dem Muster der Quell-URI übereinstimmt und
der Weiterleitungsort mit dem Muster der kanonischen URI übereinstimmt.

Der linkcheck-Builder gibt eine Warnung aus, wenn er weitergeleitete Links findet, die nicht den obigen Regeln entsprechen. Dies kann nützlich sein, um unerwartete Weiterleitungen im Modus fail-on-warnings zu erkennen.

Beispiel

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to
    # the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

Hinzugefügt in Version 4.1.

Geändert in Version 9.0: Das Setzen von linkcheck_allowed_redirects auf ein leeres Wörterbuch kann nun verwendet werden, um vor allen Weiterleitungen zu warnen, die vom linkcheck-Builder gefunden werden.

linkcheck_anchors¶

Typ:: bool
Standard:: True

Überprüft die Gültigkeit von #Ankers in Links. Da dies den Download des gesamten Dokuments erfordert, ist es bei Aktivierung erheblich langsamer.

Hinzugefügt in Version 1.2.

linkcheck_anchors_ignore¶

Typ:: Sequenz[str]
Standard:: ["^!"]

Eine Liste von regulären Ausdrücken, die Anker abgleichen, die der linkcheck-Builder beim Überprüfen der Gültigkeit von Ankern in Links überspringen soll. Dies ermöglicht beispielsweise das Überspringen von Ankern, die von der JavaScript-Website hinzugefügt wurden.

Tipp

Verwenden Sie linkcheck_anchors_ignore_for_url, um eine URL zu überprüfen, aber das Überprüfen der Anker zu überspringen.

Hinweis

Wenn Sie Anker einer bestimmten Seite oder von Seiten, die einem bestimmten Muster entsprechen, ignorieren möchten (aber trotzdem Vorkommen derselben Seite(n) überprüfen möchten, die keine Anker haben), verwenden Sie stattdessen linkcheck_ignore, zum Beispiel wie folgt:

linkcheck_ignore = [
   'https://sphinx-doc.de/en/1.7/intro.html#',
]

Hinzugefügt in Version 1.5.

linkcheck_anchors_ignore_for_url¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste oder ein Tupel von regulären Ausdrücken, die URLs abgleichen, für die der linkcheck-Builder keine Ankergültigkeit überprüfen soll. Dies ermöglicht das Überspringen von Ankerprüfungen pro Seite, während die Gültigkeit der Seite selbst weiterhin überprüft wird.

Hinzugefügt in Version 7.1.

linkcheck_exclude_documents¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von regulären Ausdrücken, die Dokumente abgleichen, in denen der linkcheck-Builder keine Linkgültigkeit überprüfen soll. Dies kann verwendet werden, um Linkverfall in Legacy- oder historischen Abschnitten der Dokumentation zuzulassen.

Beispiel

# ignore all links in documents located in a subdirectory named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

Hinzugefügt in Version 4.4.

linkcheck_ignore¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von regulären Ausdrücken, die URIs abgleichen, die bei einem linkcheck-Build nicht überprüft werden sollen.

Vom Server ausgegebene Weiterleitungen, die mit ignorierten URIs übereinstimmen, werden nicht verfolgt.

Beispiel

linkcheck_ignore = [r'https://:\d+/']

Hinzugefügt in Version 1.1.

HTTP-Anfragen¶

Diese Optionen steuern, wie der linkcheck-Builder HTTP-Anfragen stellt, einschließlich des Umgangs mit Weiterleitungen und Authentifizierung sowie der Anzahl der zu verwendenden Worker.

linkcheck_auth¶

Typ:: Sequenz[tuple[str, Any]]
Standard:: []

Übergibt Authentifizierungsinformationen bei der Ausführung eines linkcheck-Builds.

Eine Liste von (regex_pattern, auth_info)-Tupeln, wobei die Elemente

regex_pattern: Ein regulärer Ausdruck, der eine URI abgleicht.
auth_info: Authentifizierungsinformationen für diese URI. Der Wert kann alles sein, was von der requests-Bibliothek verstanden wird (siehe requests authentication für Details).

Der linkcheck-Builder verwendet den ersten passenden auth_info-Wert, den er in der Liste linkcheck_auth findet. Werte, die früher in der Liste stehen, haben also eine höhere Priorität.

Beispiel

linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

Hinzugefügt in Version 2.3.

linkcheck_allow_unauthorized¶

Typ:: bool
Standard:: False

Wenn ein Webserver mit einer HTTP-401-Antwort (nicht autorisiert) antwortet, ist das aktuelle Standardverhalten des linkcheck-Builders, den Link als „defekt“ zu behandeln. Um dieses Verhalten zu ändern, setzen Sie diese Option auf True.

Geändert in Version 8.0: Der Standardwert für diese Option wurde auf False geändert, was bedeutet, dass HTTP-401-Antworten auf überprüfte Hyperlinks standardmäßig als „defekt“ behandelt werden.

Hinzugefügt in Version 7.3.

linkcheck_case_insensitive_urls¶

Typ:: Set[str] | Sequenz[str]
Standard:: ()

Eine Sammlung von regulären Ausdrücken, die URLs abgleichen, für die der linkcheck-Builder Fall-unempfindliche Vergleiche durchführen soll. Dies ist nützlich für Links zu Websites, die Fall-unempfindlich sind oder die Groß-/Kleinschreibung von URLs normalisieren.

Standardmäßig erfordert linkcheck, dass die Ziel-URL mit der dokumentierten URL Fall-sensitiv übereinstimmt. Zum Beispiel wird ein Link zu http://example.org/PATH, der zu http://example.org/path weiterleitet, als redirected gemeldet.

Wenn die URL einem Muster entspricht, das in linkcheck_case_insensitive_urls enthalten ist, würde sie stattdessen als working gemeldet.

Um beispielsweise alle GitHub-URLs als Fall-unempfindlich zu behandeln:

linkcheck_case_insensitive_urls = [
    r'https://github\.com/.*',
]

Oder, um alle URLs als Fall-unempfindlich zu behandeln:

linkcheck_case_insensitive_urls = ['.*']

Hinweis

URI-Fragmente (HTML-Anker) werden von dieser Option nicht beeinflusst. Sie werden immer mit Fall-sensitiven Vergleichen überprüft.

Hinzugefügt in Version 9.0.

linkcheck_rate_limit_timeout¶

Typ:: int
Standard:: 300

Der linkcheck-Builder kann eine große Anzahl von Anfragen an dieselbe Website über einen kurzen Zeitraum ausgeben. Diese Einstellung steuert das Verhalten des Builders, wenn Server angeben, dass Anfragen ratenbegrenzt sind, indem sie die maximale Dauer (in Sekunden) festlegt, die der Builder zwischen den Versuchen wartet, bevor ein Fehler gemeldet wird.

Der linkcheck-Builder beachtet immer die Anweisungen des Servers zum erneuten Versuch (mithilfe des Retry-After-Headers). Andernfalls wartet linkcheck eine Minute, bevor es einen erneuten Versuch unternimmt, und verdoppelt die Wartezeit zwischen den Versuchen, bis ein Erfolg eintritt oder die linkcheck_rate_limit_timeout (in Sekunden) überschritten wird. Benutzerdefinierte Timeouts sollten als Anzahl von Sekunden angegeben werden.

Hinzugefügt in Version 3.4.

linkcheck_report_timeouts_as_broken¶

Typ:: bool
Standard:: False

Wenn linkcheck_timeout beim Warten auf eine Antwort von einem Hyperlink abläuft, meldet der linkcheck-Builder den Link standardmäßig als timeout. Um Timeouts stattdessen als broken zu melden, können Sie linkcheck_report_timeouts_as_broken auf True setzen.

Geändert in Version 8.0: Der Standardwert für diese Option wurde auf False geändert, was bedeutet, dass Timeouts, die beim Überprüfen von Hyperlinks auftreten, mit dem neuen Statuscode „timeout“ gemeldet werden.

Hinzugefügt in Version 7.3.

linkcheck_request_headers¶

Typ:: dict[str, dict[str, str]]
Standard:: {}

Ein Wörterbuch, das URLs (ohne Pfade) HTTP-Request-Headern zuordnet.

Der Schlüssel ist eine Basis-URL-Zeichenkette wie 'https://sphinx-doc.de/'. Um Header für andere Hosts anzugeben, kann "*" verwendet werden. Es passt zu allen Hosts, nur wenn die URL nicht mit anderen Einstellungen übereinstimmt.

Der Wert ist ein Wörterbuch, das den Headernamen seinem Wert zuordnet.

Beispiel

linkcheck_request_headers = {
    "https://sphinx-doc.de/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

Hinzugefügt in Version 3.1.

linkcheck_retries¶

Typ:: int
Standard:: 1

Die Anzahl der Versuche, die der linkcheck-Builder unternimmt, um eine URL zu überprüfen, bevor er sie als defekt erklärt.

Hinzugefügt in Version 1.4.

linkcheck_timeout¶

Typ:: int
Standard:: 30

Die Dauer in Sekunden, die der linkcheck-Builder auf eine Antwort nach jeder Hyperlink-Anfrage wartet.

Hinzugefügt in Version 1.1.

linkcheck_workers¶

Typ:: int
Standard:: 5

Die Anzahl der Worker-Threads, die beim Überprüfen von Links verwendet werden.

Hinzugefügt in Version 1.1.

Domain-Optionen¶

Optionen für die C-Domain¶

c_extra_keywords¶

Typ:: Set[str] | Sequenz[str]
Standard:: ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']

Eine Liste von Bezeichnern, die vom C-Parser als Schlüsselwörter erkannt werden sollen.

Hinzugefügt in Version 4.0.3.

Geändert in Version 7.4: c_extra_keywords kann jetzt ein Set sein.

c_id_attributes¶

Typ:: Sequenz[str]
Standard:: ()

Eine Sequenz von Zeichenketten, die der Parser zusätzlich als Attribute akzeptieren soll. Dies kann beispielsweise verwendet werden, wenn #define für Attribute zur Portabilität verwendet wurde.

Beispiel

c_id_attributes = [
    'my_id_attribute',
]

Hinzugefügt in Version 3.0.

Geändert in Version 7.4: c_id_attributes kann jetzt ein Tupel sein.

c_maximum_signature_line_length¶

Typ:: int | None
Standard:: None

Wenn die Länge einer Signatur in Zeichen die eingestellte Zahl überschreitet, wird jeder Parameter innerhalb der Signatur auf einer einzelnen logischen Zeile angezeigt.

Wenn None, gibt es keine maximale Länge und die gesamte Signatur wird auf einer einzigen logischen Zeile angezeigt.

Dies ist eine domainspezifische Einstellung, die maximum_signature_line_length überschreibt.

Hinzugefügt in Version 7.1.

c_paren_attributes¶

Typ:: Sequenz[str]
Standard:: ()

Eine Sequenz von Zeichenketten, die der Parser zusätzlich als Attribute mit einem Argument akzeptieren soll. Das heißt, wenn my_align_as in der Liste enthalten ist, wird my_align_as(X) als Attribut für alle Zeichenketten X analysiert, die ausgewogene Klammern aufweisen ((), [] und {}). Dies kann beispielsweise verwendet werden, wenn #define für Attribute zur Portabilität verwendet wurde.

Beispiel

c_paren_attributes = [
    'my_align_as',
]

Hinzugefügt in Version 3.0.

Geändert in Version 7.4: c_paren_attributes kann jetzt ein Tupel sein.

Optionen für die C++-Domain¶

cpp_id_attributes¶

Typ:: Sequenz[str]
Standard:: ()

Eine Sequenz von Zeichenketten, die der Parser zusätzlich als Attribute akzeptieren soll. Dies kann beispielsweise verwendet werden, wenn #define für Attribute zur Portabilität verwendet wurde.

Beispiel

cpp_id_attributes = [
    'my_id_attribute',
]

Hinzugefügt in Version 1.5.

Geändert in Version 7.4: cpp_id_attributes kann jetzt ein Tupel sein.

cpp_index_common_prefix¶

Typ:: Sequenz[str]
Standard:: ()

Eine Liste von Präfixen, die beim Sortieren von C++-Objekten im globalen Index ignoriert werden.

Beispiel

cpp_index_common_prefix = [
    'awesome_lib::',
]

Hinzugefügt in Version 1.5.

cpp_maximum_signature_line_length¶

Typ:: int | None
Standard:: None

Wenn die Länge einer Signatur in Zeichen die eingestellte Zahl überschreitet, wird jeder Parameter innerhalb der Signatur auf einer einzelnen logischen Zeile angezeigt.

Wenn None, gibt es keine maximale Länge und die gesamte Signatur wird auf einer einzigen logischen Zeile angezeigt.

Dies ist eine domainspezifische Einstellung, die maximum_signature_line_length überschreibt.

Hinzugefügt in Version 7.1.

cpp_paren_attributes¶

Typ:: Sequenz[str]
Standard:: ()

Eine Sequenz von Zeichenketten, die der Parser zusätzlich als Attribute mit einem Argument akzeptieren soll. Das heißt, wenn my_align_as in der Liste enthalten ist, wird my_align_as(X) als Attribut für alle Zeichenketten X geparst, die ausgewogene Klammern haben ((), [] und {}). Dies kann beispielsweise verwendet werden, wenn #define aus Portabilitätsgründen für Attribute verwendet wurde.

Beispiel

cpp_paren_attributes = [
    'my_align_as',
]

Hinzugefügt in Version 1.5.

Geändert in Version 7.4: cpp_paren_attributes kann jetzt ein Tupel sein.

Optionen für die Javascript-Domäne¶

javascript_maximum_signature_line_length¶

Typ:: int | None
Standard:: None

Wenn die Länge einer Signatur in Zeichen die eingestellte Zahl überschreitet, wird jeder Parameter innerhalb der Signatur auf einer einzelnen logischen Zeile angezeigt.

Wenn None, gibt es keine maximale Länge und die gesamte Signatur wird auf einer einzigen logischen Zeile angezeigt.

Dies ist eine domainspezifische Einstellung, die maximum_signature_line_length überschreibt.

Hinzugefügt in Version 7.1.

javascript_trailing_comma_in_multi_line_signatures¶

Typ:: bool
Standard:: True

Verwendet ein abschließendes Komma in Parameterlisten, die sich über mehrere Zeilen erstrecken, wenn True.

Hinzugefügt in Version 8.2.

Optionen für die Python-Domäne¶

add_module_names¶

Typ:: bool
Standard:: True

Ein boolescher Wert, der entscheidet, ob Modulnamen allen Objekt-Namen vorangestellt werden (für Objekttypen, bei denen eine Art "Modul" definiert ist), z. B. für py:function Direktiven.

modindex_common_prefix¶

Typ:: list[str]
Standard:: []

Eine Liste von Präfixen, die bei der Sortierung des Python-Modulindexes ignoriert werden (z. B. wenn dies auf ['foo.'] gesetzt ist, wird foo.bar unter B und nicht unter F angezeigt). Dies kann nützlich sein, wenn Sie ein Projekt dokumentieren, das aus einem einzigen Paket besteht.

Vorsicht

Funktioniert derzeit nur für den HTML-Builder.

Hinzugefügt in Version 0.6.

python_display_short_literal_types¶

Typ:: bool
Standard:: False

Dieser Wert steuert, wie Literal-Typen angezeigt werden.

Beispiele¶

Die folgenden Beispiele verwenden die folgende py:function Direktive

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

Wenn False, werden Literal-Typen gemäß der Standard-Python-Syntax angezeigt, d. h.:

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

Wenn True, werden Literal-Typen mit einer kurzen, von PEP 604 inspirierten Syntax angezeigt, d. h.:

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

Hinzugefügt in Version 6.2.

python_maximum_signature_line_length¶

Typ:: int | None
Standard:: None

Wenn die Länge einer Signatur in Zeichen die eingestellte Zahl überschreitet, wird jeder Parameter innerhalb der Signatur auf einer einzelnen logischen Zeile angezeigt.

Wenn None, gibt es keine maximale Länge und die gesamte Signatur wird auf einer einzigen logischen Zeile angezeigt.

Dies ist eine domainspezifische Einstellung, die maximum_signature_line_length überschreibt.

Für die Python-Domäne hängt die Signaturlänge davon ab, ob die Typparameter oder die Liste der Argumente formatiert werden. Bei ersterem ignoriert die Signaturlänge die Länge der Argumentliste; bei letzterer ignoriert die Signaturlänge die Länge der Typparameterliste.

Zum Beispiel wird mit python_maximum_signature_line_length = 20 nur die Liste der Typparameter umgebrochen, während die Argumentliste in einer einzigen Zeile gerendert wird

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

Hinzugefügt in Version 7.1.

python_trailing_comma_in_multi_line_signatures¶

Typ:: bool
Standard:: True

Verwendet ein abschließendes Komma in Parameterlisten, die sich über mehrere Zeilen erstrecken, wenn True.

Hinzugefügt in Version 8.2.

python_use_unqualified_type_names¶

Typ:: bool
Standard:: False

Unterdrückt den Modulnamen der Python-Referenz, wenn er aufgelöst werden kann.

Hinzugefügt in Version 4.0.

Vorsicht

Dieses Feature ist experimentell.

trim_doctest_flags¶

Typ:: bool
Standard:: True

Entfernt Doctest-Flags (Kommentare wie # doctest: FLAG, ...) am Ende von Zeilen und <BLANKLINE>-Markierungen für alle Codeblöcke, die interaktive Python-Sitzungen (d. h. Doctests) zeigen. Weitere Möglichkeiten zum Einbinden von Doctests finden Sie in der Erweiterung doctest.

Hinzugefügt in Version 1.0.

Geändert in Version 1.1: Entfernt jetzt auch <BLANKLINE>.

Erweiterungsoptionen¶

Erweiterungen haben oft eigene Konfigurationsoptionen. Die für die First-Party-Erweiterungen von Sphinx werden auf der Seite der jeweiligen Erweiterung dokumentiert.

Beispiel Konfigurationsdatei¶

# -- Project information -----------------------------------------------------
# https://sphinx-doc.de/en/master/usage/configuration.html#project-information

project = 'Test Project'
copyright = '2000-2042, The Test Project Authors'
author = 'The Authors'
version = release = '4.16'

# -- General configuration ------------------------------------------------
# https://sphinx-doc.de/en/master/usage/configuration.html#general-configuration

exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
]
extensions = []
language = 'en'
master_doc = 'index'
pygments_style = 'sphinx'
source_suffix = '.rst'
templates_path = ['_templates']

# -- Options for HTML output ----------------------------------------------
# https://sphinx-doc.de/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']