LaTeX-Anpassung

Im Gegensatz zu HTML-Buildern profitiert der latex-Builder nicht von vorbereiteten Themes. Die Optionen für LaTeX-Ausgabe, insbesondere die Variable latex_elements, bietet die Schnittstelle für die Anpassung. Zum Beispiel

# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
    'passoptionstopackages': r'''
\PassOptionsToPackage{svgnames}{xcolor}
''',
    'fontpkg': r'''
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont{DejaVu Sans Mono}
''',
    'preamble': r'''
\usepackage[titles]{tocloft}
\cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
\setlength{\cftchapnumwidth}{0.75cm}
\setlength{\cftsecindent}{\cftchapnumwidth}
\setlength{\cftsecnumwidth}{1.25cm}
''',
    'sphinxsetup': 'TitleColor=DarkGoldenrod',
    'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
    'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'

Hinweis

Beachten Sie, dass Backslashes in Python-String-Literalen verdoppelt werden müssen, um eine Interpretation als Escape-Sequenzen zu vermeiden. Alternativ können Sie Rohzeichenketten verwenden, wie oben gezeigt.

Die Konfigurationseinstellung latex_elements

Ein Wörterbuch, das LaTeX-Snippets enthält, die die von Sphinx normalerweise in die generierten .tex-Dateien eingefügten überschreiben. Sein Schlüssel 'sphinxsetup' wird separat beschrieben. Es ermöglicht auch lokale Konfigurationen, die über raw-Direktiven in generierte Dateien eingefügt werden. Zum Beispiel wird in der PDF-Dokumentation dieses Kapitel besonders formatiert, wie später beschrieben wird.

Schlüssel, die Sie möglicherweise überschreiben möchten, sind:

'papersize'

Papiergrößenoption der Dokumentenklasse ('a4paper' oder 'letterpaper')

Standard: 'letterpaper'

'pointsize'

Punktgrößenoption der Dokumentenklasse ('10pt', '11pt' oder '12pt')

Standard: '10pt'

'pxunit'

Der Wert von px bei Verwendung in Bildattributen width und height. Der Standardwert ist '0.75bp', was 96px=1in erreicht (in TeX 1in = 72bp = 72.27pt). Um zum Beispiel 100px=1in zu erhalten, verwenden Sie '0.01in' oder '0.7227pt' (letzteres führt dazu, dass TeX einen genaueren Wert berechnet, aufgrund der kleineren Einheit in der Spezifikation); für 72px=1in verwenden Sie einfach '1bp'; für 90px=1in verwenden Sie '0.8bp' oder '0.803pt'.

Standard: '0.75bp'

Hinzugefügt in Version 1.5.

'passoptionstopackages'

Eine Zeichenkette, die früh im Präambulum platziert wird und dafür bestimmt ist, Befehle wie \PassOptionsToPackage{options}{foo} zu enthalten.

Hinweis

Sie kann auch zum Laden von LaTeX-Paketen sehr früh im Präambulum verwendet werden. Zum Beispiel ist das Paket fancybox inkompatibel damit, über den Schlüssel 'preamble' geladen zu werden; es muss früher geladen werden.

Standard: ''

Hinzugefügt in Version 1.4.

'babel'

Einbindung des Pakets „babel“, Standard ist r'\usepackage{babel}' (die passende Dokumentensprachzeichenkette wird als Klassenoption übergeben, und english wird verwendet, wenn keine Sprache angegeben ist). Für japanische Dokumente ist der Standard die leere Zeichenkette.

Mit XeLaTeX und LuaLaTeX konfiguriert Sphinx das LaTeX-Dokument so, dass es polyglossia verwendet. Man sollte sich jedoch bewusst sein, dass das aktuelle babel seine Unterstützung für Unicode-Engines in den letzten Jahren verbessert hat und für einige Sprachen sinnvoll sein kann, babel gegenüber polyglossia zu bevorzugen.

Hinweis

Nachdem ein Kern-LaTeX-Schlüssel wie dieser geändert wurde, bereinigen Sie das LaTeX-Build-Verzeichnis vor dem nächsten PDF-Build, da sonst verbleibende Hilfsdateien den Build wahrscheinlich brechen.

Standard: r'\usepackage{babel}' (für japanische Dokumente)

Geändert in Version 1.5: Für latex_engine auf 'xelatex' gesetzt, ist der Standard '\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'.

Geändert in Version 1.6: 'lualatex' verwendet die gleiche Standardeinstellung wie 'xelatex'.

Geändert in Version 1.7.6: Für Französisch mit 'xelatex' (nicht 'lualatex') ist der Standard die Verwendung von babel, nicht von polyglossia.

Geändert in Version 7.4.0: Für Französisch mit 'lualatex' ist der Standard die Verwendung von babel.

'fontpkg'

Schriftartpaket-Einbindung. Der Standard mit 'pdflatex' ist

r"""\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand\ttdefault{txtt}
"""

Für 'xelatex' und 'lualatex' hingegen werden die Befehle \setmainfont, \setsansfont und \setmonofont des LaTeX-Pakets fontspec (eingebunden über 'fontenc') verwendet, um die OpenType-Schriften GNU FreeSerif, FreeSans und FreeMono (skaliert mit dem Verhältnis 0.9) als Dokumentenschriften einzurichten.

Geändert in Version 1.2: Standardmäßig '', wenn die language das kyrillische Skript verwendet.

Geändert in Version 2.0: Enthält einige Schriftart-Substitutionsbefehle zur Unterstützung gelegentlicher griechischer oder kyrillischer Zeichen in einem Dokument mit der 'pdflatex'-Engine. Ab Version 4.0.0 wurden diese Befehle in den Schlüssel 'fontsubstitution' verschoben.

Geändert in Version 4.0.0: Die Standard-Schriftarteinstellung wurde geändert. Wie oben gezeigt, werden weiterhin Times- und Helvetica-Klone für Serif und Sans-Serif verwendet, aber über bessere, vollständigere TeX-Schriften und zugehörige LaTeX-Pakete. Die Monospace-Schrift wurde geändert, um besser zum Times-Klon zu passen.

Geändert in Version 8.1.0: Die Monospace-Schrift FreeMono, die mit Unicode-Engines verwendet wird, wird in der Skalierung 0.9 geladen. Dies ersetzt den früheren Mechanismus über 'fvset', der Codeblöcke so konfigurierte, dass sie \small verwenden. Inline-Literale passen nun besser in den umgebenden Text, und es ist einfacher, benutzerdefinierte Schriften einzurichten, da 'fvset' standardmäßig nicht mehr eingreift.

'fncychap'

Einbindung des Pakets „fncychap“ (das schicke Kapitelüberschriften erzeugt), Standard ist r'\usepackage[Bjarne]{fncychap}' für englische Dokumente (diese Option wird von Sphinx leicht angepasst), r'\usepackage[Sonny]{fncychap}' für internationalisierte Dokumente (da der „Bjarne“-Stil englische Zahlen ausgeschrieben verwendet). Andere „fncychap“-Stile, die Sie ausprobieren können, sind „Lenny“, „Glenn“, „Conny“, „Rejne“ und „Bjornstrup“. Sie können dies auch auf '' setzen, um fncychap zu deaktivieren.

Standard: r'\usepackage[Bjarne]{fncychap}' für englische Dokumente, r'\usepackage[Sonny]{fncychap}' für internationalisierte Dokumente und '' für japanische Dokumente.

'preamble'

Zusätzlicher Präambulum-Inhalt. Man kann alle benötigten Makros in eine Datei mystyle.tex.txt im Projekt-Quellverzeichnis verschieben und LaTeX diese zur Laufzeit importieren lassen.

'preamble': r'\input{mystyle.tex.txt}',
# or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
'preamble': r'\usepackage{mystyle}',

Es ist dann notwendig, latex_additional_files entsprechend zu setzen, zum Beispiel

latex_additional_files = ["mystyle.sty"]

Verwenden Sie nicht .tex als Suffix, da die Datei selbst dem PDF-Build-Prozess unterliegt. Verwenden Sie stattdessen .tex.txt oder .sty, wie in den Beispielen oben.

Standard: ''

'figure_align'

LaTeX-Abbildung-Float-Ausrichtung. Wenn eine Abbildung nicht auf die aktuelle Seite passt, wird sie auf die nächste Seite „gefloaten“, kann aber von anderem Text vorangestellt werden. Wenn Ihnen dieses Verhalten nicht gefällt, verwenden Sie „H“, was das Floaten deaktiviert und Abbildungen strikt in der Reihenfolge positioniert, in der sie in der Quelle erscheinen.

Standard: 'htbp' (hier, oben, unten, Seite)

Hinzugefügt in Version 1.3.

'atendofbody'

Zusätzlicher Dokumenteninhalt (kurz vor den Indizes).

Standard: ''

Hinzugefügt in Version 1.5.

'extrapackages'

Zusätzliche LaTeX-Pakete. Zum Beispiel

latex_elements = {
    'extrapackages': r'\usepackage{isodate}'
}

Die angegebenen LaTeX-Pakete werden vor dem hyperref-Paket und den von Sphinx-Erweiterungen geladenen Paketen geladen.

Hinweis

Wenn Sie zusätzliche LaTeX-Pakete nach hyperref laden möchten, verwenden Sie stattdessen den Schlüssel 'preamble'.

Standard: ''

Hinzugefügt in Version 2.3.

'footer'

Zusätzlicher Fußzeileninhalt (vor den Indizes).

Standard: ''

Veraltet seit Version 1.5: Verwenden Sie stattdessen den Schlüssel 'atendofbody'.

Schlüssel, die nicht überschrieben werden müssen, außer in Sonderfällen sind:

'extraclassoptions'

Der Standard ist die leere Zeichenkette. Beispiel: 'extraclassoptions': 'openany' erlaubt Kapiteln (für Dokumente vom Typ 'manual'), auf jeder Seite zu beginnen.

Standard: ''

Hinzugefügt in Version 1.2.

Geändert in Version 1.6: Diese Dokumentation wurde hinzugefügt.

'maxlistdepth'

LaTeX erlaubt standardmäßig maximal 6 Ebenen für verschachtelte Listen und zitatähnliche Umgebungen, mit maximal 4 nummerierten Listen und 4 Aufzählungslisten. Das Setzen dieses Schlüssels z. B. auf '10' (als Zeichenkette) erlaubt bis zu 10 verschachtelte Ebenen (aller Art). Wenn er leer bleibt, wird die LaTeX-Standardeinstellung befolgt.

Warnung

• Die Verwendung dieses Schlüssels kann sich als inkompatibel mit einigen LaTeX-Paketen oder speziellen Dokumentenklassen erweisen, die ihre eigene Listenanpassung durchführen.

• Die Einstellung des Schlüssels wird stillschweigend *ignoriert*, wenn \usepackage{enumitem} im Dokumentenpräambulum ausgeführt wird. Verwenden Sie stattdessen die dedizierten Befehle dieses LaTeX-Pakets.

Standard: 6

Hinzugefügt in Version 1.5.

'inputenc'

Einbindung des Pakets „inputenc“.

Standard: r'\usepackage[utf8]{inputenc}' bei Verwendung von pdflatex, sonst ''.

Hinweis

Wenn utf8x anstelle von utf8 verwendet wird, ist es zwingend erforderlich, das LaTeX-Präambulum um geeignete Befehle wie \PreloadUnicodePage{<number>} zu erweitern, gemäß der utf8x-Dokumentation (texdoc ucs auf einer TeXLive-basierten TeX-Installation). Andernfalls können unerwartete und möglicherweise schwer zu findende Probleme (d.h. die keinen Build-Absturz verursachen) in der PDF auftreten, insbesondere in Bezug auf Hyperlinks.

Selbst wenn diese Vorsichtsmaßnahmen getroffen werden, kann der PDF-Build über die pdflatex-Engine aufgrund von LaTeX-Upstream-Versionen, die nicht vollständig mit utf8x kompatibel sind, abstürzen. Zum Beispiel können unter bestimmten Umständen im Zusammenhang mit Codeblöcken oder beim Versuch, Bilder einzufügen, deren Dateinamen Unicode-Zeichen enthalten. Tatsächlich hat LaTeX-Upstream mit der pdflatex-Engine seit 2015 die native Unterstützung für Unicode etwas verbessert und wird immer inkompatibler mit utf8x. Insbesondere seit der LaTeX-Version vom Oktober 2019 können Dateinamen Unicode-Zeichen und sogar Leerzeichen verwenden. Auf Sphinx-Ebene bedeutet dies z. B., dass die Direktiven image und figure jetzt mit solchen Dateinamen für PDF über LaTeX-Ausgabe kompatibel sind. Dies ist jedoch fehlerhaft, wenn utf8x verwendet wird.

Geändert in Version 1.4.3: Zuvor wurde r'\usepackage[utf8]{inputenc}' für alle Compiler verwendet.

'cmappkg'

Einbindung des Pakets „cmap“.

Standard: r'\usepackage{cmap}'

Hinzugefügt in Version 1.2.

'fontenc'

Sein Standard für 'pdflatex' als latex_engine ist r'\usepackage[T1]{fontenc}'. Ersetzen Sie ihn (bei Verwendung von 'pdflatex') durch

• r'\usepackage[X2,T1]{fontenc}', wenn Sie gelegentlich kyrillische Buchstaben benötigen (физика частиц),

• r'\usepackage[LGR,T1]{fontenc}', wenn Sie gelegentlich griechische Buchstaben benötigen (Σωματιδιακή φυσική),

• r'\usepackage[LGR,X2,T1]{fontenc}', wenn Sie beides benötigen.

Die TeX-Installation benötigt möglicherweise einige zusätzliche Pakete. Zum Beispiel auf Ubuntu Xenial

• texlive-lang-greek und cm-super werden für Griechisch (LGR) benötigt,

• texlive-lang-cyrillic und cm-super werden für Kyrillisch (X2) benötigt.

Mit 'xelatex' und 'lualatex' ist die Unterstützung für Griechisch und Kyrillisch sofort verfügbar: dieser Schlüssel 'fontenc' bindet standardmäßig das LaTeX-Paket fontspec (mit einigen unten beschriebenen Extras) ein und wählt die GNU FreeSerif-Schriftart als Körpertextschrift. Siehe 'fontpkg'.

Geändert in Version 1.5: Standardmäßig r'\usepackage{fontspec}', wenn latex_engine auf 'xelatex' gesetzt ist.

Geändert in Version 1.6: Standardmäßig r'\usepackage{fontspec}', wenn latex_engine auf 'lualatex' gesetzt ist.

Geändert in Version 2.0: 'lualatex' führt zusätzlich \defaultfontfeatures[\rmfamily,\sffamily]{} aus, um Ligaturen für << und >> zu deaktivieren.

Geändert in Version 2.0: Zusätzliche LaTeX-Konfiguration wird automatisch ausgeführt, wenn LGR, T2A oder X2 in diesem Schlüssel erkannt werden, um gelegentliches Griechisch oder Kyrillisch mit 'pdflatex' zu unterstützen.

Geändert in Version 2.2.1: Dokumente mit Griechisch als Hauptsprache werden standardmäßig auf 'xelatex' gesetzt und sollten den Schlüssel 'fontenc' nicht setzen, was fontspec laden würde.

Geändert in Version 2.3.0: 'xelatex' führt \defaultfontfeatures[\rmfamily,\sffamily]{} aus, um die Kontraktion von -- zu einem Gedankenstrich zu vermeiden und auch die Umwandlung von geraden Anführungszeichen in geschwungene Anführungszeichen (was sonst auch bei smartquotes auf False geschehen würde).

'fontsubstitution'

Ignoriert, wenn 'fontenc' nicht so konfiguriert wurde, dass es LGR oder X2 (oder T2A) verwendet. Wenn der Schlüssel 'fontpkg' für die Verwendung mit TeX-Schriften konfiguriert ist, die bekanntermaßen in den LGR- oder X2-Kodierungen verfügbar sind, setzen Sie diesen auf die leere Zeichenkette. Andernfalls belassen Sie ihn beim Standardwert.

Ignoriert bei latex_engine-Werten, die nicht 'pdflatex' sind.

Hinzugefügt in Version 4.0.0.

'textgreek'

Zur Unterstützung gelegentlicher griechischer Buchstaben.

Er wird ignoriert bei 'platex', 'xelatex' oder 'lualatex' als latex_engine und ist standardmäßig entweder die leere Zeichenkette oder r'\usepackage{textalpha}' für 'pdflatex', je nachdem, ob der Schlüssel 'fontenc' mit LGR verwendet wurde oder nicht. Nur erfahrene LaTeX-Benutzer möchten diesen Schlüssel möglicherweise anpassen.

Er kann auch als r'\usepackage{textalpha,alphabeta}' verwendet werden, um 'pdflatex' die Unterstützung für griechische Unicode-Eingabe im math-Kontext zu ermöglichen. Zum Beispiel wird :math:`α` (U+03B1) als \(\alpha\) gerendert.

Standard: r'\usepackage{textalpha}' oder '', wenn fontenc die Option LGR nicht enthält.

Hinzugefügt in Version 2.0.

'geometry'

Einbindung des Pakets „geometry“, standardmäßig r'\usepackage{geometry}' oder r'\usepackage[dvipdfm]{geometry}' für japanische Dokumente. Die Sphinx-LaTeX-Stildatei führt zusätzlich aus:

\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}

was über entsprechende ‚sphinxsetup‘-Optionen angepasst werden kann.

Hinzugefügt in Version 1.5.

Geändert in Version 1.5.2: dvipdfm-Option, wenn latex_engine 'platex' ist.

Hinzugefügt in Version 1.5.3: Die ‚sphinxsetup‘-Schlüssel für die Ränder.

Geändert in Version 1.5.3: Die Position in der LaTeX-Datei wurde nach \usepackage{sphinx} und \sphinxsetup{..} verschoben, und damit auch nach der Einfügung des Schlüssels 'fontpkg'. Dies geschieht, um die Papierlayout-Optionen für japanische Dokumente speziell zu handhaben: Die Textbreite wird auf ein ganzzahliges Vielfaches der *zenkaku*-Breite und die Texthöhe auf ein ganzzahliges Vielfaches der Grundlinie gesetzt. Siehe die hmargin-Dokumentation für weitere Details.

'hyperref'

Einbindung des Pakets „hyperref“; lädt auch das Paket „hypcap“ und gibt \urlstyle{same} aus. Dies geschieht nach dem Laden der Datei sphinx.sty und vor der Ausführung des Inhalts des Schlüssels 'preamble'.

Aufmerksamkeit

Das Laden der Pakete „hyperref“ und „hypcap“ ist obligatorisch.

Hinzugefügt in Version 1.5: Zuvor geschah dies innerhalb von sphinx.sty.

'maketitle'

Aufruf von „maketitle“. Überschreiben Sie dies, wenn Sie eine anders gestaltete Titelseite generieren möchten.

Hinweis

Wenn der Schlüsselwert auf r'\newcommand\sphinxbackoftitlepage{<Zusätzlicher Inhalt>}\sphinxmaketitle' gesetzt ist, wird <Zusätzlicher Inhalt> auf der Rückseite der Titelseite gesetzt (nur bei Dokumentenklasse 'manual').

Standard: r'\sphinxmaketitle'

Geändert in Version 1.8.3: Der ursprüngliche \maketitle aus der Dokumentenklasse wird nicht überschrieben, sodass er als Teil einer benutzerdefinierten Einstellung für diesen Schlüssel wiederverwendbar ist.

Hinzugefügt in Version 1.8.3: Das optionale Makro \sphinxbackoftitlepage. Es kann auch innerhalb des Schlüssels 'preamble' anstelle dieses Schlüssels definiert werden.

'releasename'

Der Wert, der dem 'release'-Element auf der Titelseite vorangestellt wird. Wie bei *Titel* und *Autor*, die in den Tupeln von latex_documents verwendet werden, wird er als LaTeX-Markup eingefügt.

Standard: 'Release'

'tableofcontents'

Aufruf von „tableofcontents“. Der Standardwert r'\sphinxtableofcontents' ist ein Wrapper für ein unverändertes \tableofcontents, das selbst durch vom Benutzer geladene Pakete angepasst werden kann. Überschreiben Sie dies, wenn Sie ein anderes Inhaltsverzeichnis generieren oder Inhalte zwischen der Titelseite und dem Inhaltsverzeichnis platzieren möchten.

Standard: r'\sphinxtableofcontents'

Geändert in Version 1.5: Zuvor wurde die Bedeutung von \tableofcontents selbst von Sphinx modifiziert. Dies führte zu einer Inkompatibilität mit speziellen Paketen, die es ebenfalls modifizieren, wie „tocloft“ oder „etoc“.

'transition'

Befehle zur Anzeige von Übergängen. Überschreiben Sie dies, wenn Sie Übergänge anders anzeigen möchten.

Standard: '\n\n\\bigskip\\hrule\\bigskip\n\n'

Hinzugefügt in Version 1.2.

Geändert in Version 1.6: Entfernung unnötiger {}, die sich früher nach \hrule befanden.

'makeindex'

Aufruf von „makeindex“, das letzte, bevor \begin{document} kommt. Mit r'\usepackage[columns=1]{idxlayout}\makeindex' wird der Index nur eine Spalte verwenden. Möglicherweise müssen Sie das idxlayout LaTeX-Paket installieren.

Standard: r'\makeindex'

'printindex'

„printindex“-Aufruf, das Letzte in der Datei. Überschreiben Sie diese Option, wenn Sie den Index anders generieren, etwas nach dem Index anhängen oder die Schriftart ändern möchten. Da LaTeX den Index im Zweispaltenmodus verwendet, ist es oft ratsam, diesen Schlüssel auf r'\footnotesize\raggedright\printindex' zu setzen. Oder, um einen einspaltigen Index zu erhalten, verwenden Sie r'\def\twocolumn[#1]{#1}\printindex' (dieser Trick kann fehlschlagen, wenn eine benutzerdefinierte Dokumentenklasse verwendet wird; versuchen Sie dann den idxlayout-Ansatz, der in der Dokumentation des 'makeindex'-Schlüssels beschrieben wird).

Standard: r'\printindex'

'fvset'

Anpassung des fancyvrb LaTeX-Pakets.

Der Standardwert ist r'\fvset{fontsize=auto}', was bedeutet, dass die Schriftgröße korrekt angepasst wird, wenn ein Codeblock in einer Fußnote endet. Möglicherweise müssen Sie dies ändern, wenn Sie eine benutzerdefinierte Monospace-Schriftart verwenden, z. B. auf r'\fvset{fontsize=\small}' setzen, wenn diese Courier-ähnlich ist (für Unicode-Engines wird empfohlen, stattdessen die Scale-Schnittstelle des LaTeX-Befehls \setmonofont aus fontspec zu verwenden).

Standard: r'\fvset{fontsize=auto}'

Hinzugefügt in Version 1.8.

Geändert in Version 2.0: Für 'xelatex' und 'lualatex' wird standardmäßig r'\fvset{fontsize=\small}' verwendet, da dies an die relativen Breiten der FreeFont-Familie angepasst ist.

Geändert in Version 4.0.0: Standard für 'pdflatex' geändert. Zuvor wurde r'\fvset{fontsize=\small}' verwendet.

Geändert in Version 4.1.0: Standard für chinesische Dokumente geändert auf r'\fvset{fontsize=\small,formatcom=\xeCJKVerbAddon}'

Geändert in Version 8.1.0: Standard für 'xelatex' und 'lualatex' geändert, um ebenfalls r'\fvset{fontsize=auto}' zu sein. Die Neuskalierung für die Standard-Monospace-Schriftart FreeMono wird nun über die fontspec-Schnittstelle des LaTeX-Pakets gesetzt. Siehe 'fontpkg'.

Schlüssel, die von anderen Optionen gesetzt werden und daher nicht überschrieben werden sollten, sind

'docclass' 'classoptions' 'title' 'release' 'author'

Die sphinxsetup Konfigurationseinstellung

Hinzugefügt in Version 1.5.

Der 'sphinxsetup' Schlüssel von latex_elements bietet eine LaTeX-ähnliche Anpassungsschnittstelle

latex_elements = {
    'sphinxsetup': 'key1=value1, key2=value2, ...',
}

Die LaTeX-Syntax für boolesche Schlüssel erfordert *kleingeschriebene* true oder false, z. B. 'sphinxsetup': "verbatimwrapslines=false". Wenn ein boolescher Schlüssel auf true gesetzt wird, ist =true optional. Leerzeichen um Kommas und Gleichheitszeichen werden ignoriert, Leerzeichen innerhalb von LaTeX-Makros können wichtig sein. Verwenden Sie keine Anführungszeichen, um Zeichenketten- oder numerische Werte einzuschließen.

Die 'sphinxsetup' ist standardmäßig leer. Wenn nicht leer, wird sie als Argument an das Makro \sphinxsetup im Präambel des Dokuments übergeben, wie folgt:

\usepackage{sphinx}
\sphinxsetup{key1=value1, key2=value2,...}

Es ist möglich, Verwendungen des LaTeX-Makros \sphinxsetup direkt in den Dokumentenkörper einzufügen, über die raw-Direktive

.. raw:: latex

   \begingroup
   \sphinxsetup{%
      TitleColor=DarkGoldenrod,
      ... more comma separated key=value using LaTeX syntax ...
   }

All elements here will be under the influence of the raw ``\sphinxsetup``
settings.

.. raw:: latex

   \endgroup

From here on, the raw ``\sphinxsetup`` has no effect anymore.

Dies ist die Technik, die verwendet wurde, um insbesondere den vorliegenden Teil der Dokumentation für die PDF-Ausgabe zu gestalten. Die tatsächlich verwendeten Optionen finden Sie oben in doc/latex.rst im Entwicklungsrepository.

Die im obigen Beispiel verwendete Farbe ist verfügbar, indem die Option svgnames an das Paket „xcolor“ übergeben wurde

latex_elements = {
    'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
}

bookmarksdepth

Steuert die Tiefe des einklappbaren Lesezeichen-Panels in der PDF-Datei. Kann entweder eine Zahl sein (z. B. 3) oder ein LaTeX-Gliederungsname (z. B. subsubsection, d. h. ohne Backslash). Details finden Sie in der hyperref LaTeX-Dokumentation.

Standard: 5

Hinzugefügt in Version 4.0.0.

hmargin, vmargin

Die Abmessungen der horizontalen (bzw. vertikalen) Ränder, übergeben als Option hmargin (bzw. vmargin) an das Paket geometry. Beispiel

'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',

Japanische Dokumente akzeptieren derzeit nur das eindimensionale Format für diese Parameter. Das Paket geometry erhält dann geeignete Optionen, um die Textbreite auf ein ganzzahliges Vielfaches der *zenkaku*-Breite und die Text Höhe auf ein ganzzahliges Vielfaches des Zeilenabstands einzustellen, mit der nächstbesten Passung für die Ränder.

Standard: 1in (entspricht {1in,1in})

Hinweis

Für japanische Dokumente mit 'manual' docclass und Punktgröße 11pt oder 12pt, verwenden Sie die zusätzliche Dokumentenklassenoption nomag (siehe 'extraclassoptions' Schlüssel von latex_elements) oder sogenannte TeX-„true“-Einheiten

'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',

Hinzugefügt in Version 1.5.3.

marginpar

Die LaTeX-Dimension \marginparwidth. Für japanische Dokumente wird der Wert auf das nächste ganzzahlige Vielfache der *zenkaku*-Breite geändert.

Standard: 0.5in

Hinzugefügt in Version 1.5.3.

mathnumsep

Dies entspricht standardmäßig dem String (ohne Anführungszeichen!), wie er von math_numsep gesetzt wird (der selbst standardmäßig auf '.' gesetzt ist). Verwenden Sie ihn, wenn eine andere Einstellung für die LaTeX-Ausgabe benötigt wird.

Hinzugefügt in Version 8.1.0.

verbatimwithframe

Boolean, um anzugeben, ob code-blocks und Literal-Includes gerahmt sind. Wenn diese Option auf false gesetzt wird, wird die Verwendung des Pakets „framed“ nicht deaktiviert, da es immer noch für die optionale Hintergrundfarbe verwendet wird.

Standard: true.

verbatimwrapslines

Boolean, um anzugeben, ob lange Zeilen in code-block-Inhalten umgebrochen werden.

Wenn true, können Zeilenumbrüche an Leerzeichen erfolgen (das letzte Leerzeichen vor dem Zeilenumbruch wird mit einem speziellen Symbol dargestellt) und an ASCII-Satzzeichen (d. h. nicht an Buchstaben oder Ziffern). Wenn eine lange Zeichenkette keine Bruchpunkte aufweist, wird sie in die nächste Zeile verschoben. Wenn ihre Länge die Zeilenbreite überschreitet, wird sie überlaufen.

Standard: true

verbatimforcewraps

Boolean, um anzugeben, ob lange Zeilen in code-block-Inhalten zwangsweise umgebrochen werden sollen, um durch lange Zeichenketten niemals zu überlaufen.

Hinweis

Es wird davon ausgegangen, dass der LaTeXFormatter von Pygments nicht mit den Optionen texcomments oder ähnlichen verwendet wurde, die zusätzliche (beliebige) LaTeX-Markups zulassen.

Außerdem ist bei latex_engine auf 'pdflatex' nur die Standard-LaTeX-Behandlung von Unicode-Codepunkten, d. h. utf8, nicht aber utf8x, zulässig.

Standard: false

Hinzugefügt in Version 3.5.0.

verbatimmaxoverfull

Eine Zahl. Wenn eine nicht umbrechbare lange Zeichenkette länger als die gesamte Zeilenbreite plus dieser Anzahl von Zeichen ist und der verbatimforcewraps-Modus aktiviert ist, wird die Eingabezeile mit dem erzwungenen Algorithmus zurückgesetzt, der an jedem Zeichen Bruchpunkte anwendet.

Standard: 3

Hinzugefügt in Version 3.5.0.

verbatimmaxunderfull

Eine Zahl. Wenn der verbatimforcewraps-Modus angewendet wird und nach dem Umbruch der Zeilen an Leerzeichen und Satzzeichen der erste Teil der aufgeteilten Zeile mindestens diese Anzahl von Zeichen benötigt, um die verfügbare Breite zu füllen, wird die Eingabezeile mit dem erzwungenen Algorithmus zurückgesetzt.

Da der Standardwert auf einen hohen Wert gesetzt ist, wird der erzwungene Algorithmus nur im Überlauf-Fall ausgelöst, d. h. bei Vorhandensein einer Zeichenkette, die länger als die volle Zeilenbreite ist. Setzen Sie diesen Wert auf 0, um alle Eingabezeilen hart am aktuellen verfügbaren Zeilenumbruch umzubrechen.

latex_elements = {
    'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
}

Dies kann lokal für einen bestimmten Codeblock über die Verwendung von rohen LaTeX-Direktiven erfolgen, um geeignete \sphinxsetup (davor und danach) in die LaTeX-Datei einzufügen.

Standard: 100

Hinzugefügt in Version 3.5.0.

verbatimhintsturnover

Boolean, um anzugeben, ob Codeblöcke bei Seitenumbrüchen Hinweise wie „Fortsetzung auf nächster Seite“ und „Fortsetzung von vorheriger Seite“ anzeigen.

Standard: true

Hinzugefügt in Version 1.6.3.

Geändert in Version 1.7: Der Standardwert wurde von false auf true geändert.

verbatimcontinuedalign, verbatimcontinuesalign

Horizontale Position relativ zum gerahmten Inhalt: entweder l (linksbündig), r (rechtsbündig) oder c (zentriert).

Standard: r

Hinzugefügt in Version 1.7.

parsedliteralwraps

Boolean, um anzugeben, ob lange Zeilen in parsed-literal-Inhalten umgebrochen werden sollen.

Standard: true

Hinzugefügt in Version 1.5.2: Setzen Sie diesen Optionswert auf false, um das frühere Verhalten wiederherzustellen.

inlineliteralwraps

Boolean, um anzugeben, ob Zeilenumbrüche in Inline-Literalen erlaubt sind: aber zusätzliche mögliche Bruchpunkte (zusätzlich zu denen, die LaTeX an Leerzeichen oder zur Silbentrennung erlaubt) werden derzeit nur nach den Zeichen . , ; ? ! / und \ eingefügt. Aufgrund von TeX-Interna wird der Leerraum in der Zeile gedehnt (oder gestaucht), um den Zeilenumbruch zu ermöglichen.

Standard: true

Hinzugefügt in Version 1.5: Setzen Sie diesen Optionswert auf false, um das frühere Verhalten wiederherzustellen.

Geändert in Version 2.3.0: Mögliche Bruchpunkte an \-Zeichen hinzugefügt.

verbatimvisiblespace

Wenn eine lange Codezeile geteilt wird, wird das letzte Leerzeichen aus der Quellcodezeile direkt vor der Umbruchstelle mit diesem Wert gesetzt.

Standard: \textcolor{red}{\textvisiblespace}

verbatimcontinued

Ein LaTeX-Makro, das am Anfang von fortgesetzten Codezeilen eingefügt wird. Seine (komplizierte...) Standardeinstellung setzt einen kleinen roten Haken, der nach rechts zeigt

\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}

Geändert in Version 1.5: Das Umbrechen von langen Codezeilen wurde in Version 1.4.2 hinzugefügt. Die Standarddefinition des Fortsetzungssymbols wurde in Version 1.5 geändert, um verschiedene Schriftgrößen zu berücksichtigen (z. B. können Codeblöcke in Fußnoten stehen).

Hinweis

Werte für Farbschlüssel müssen entweder

• der Syntax des LaTeX-Befehls \definecolor folgen, z. B. etwas wie VerbatimColor={rgb}{0.2,0.3,0.5} oder {RGB}{37,23,255} oder {gray}{0.75} oder {HTML}{808080} oder...

• oder der Syntax des Befehls \colorlet aus dem Paket xcolor folgen, z. B. VerbatimColor=red!10 oder red!50!green oder -red!75 oder MyPreviouslyDefinedColor oder… Konsultieren Sie die xcolor-Dokumentation für diese Syntax.

Geändert in Version 5.3.0: Früher wurde nur die \definecolor-Syntax akzeptiert.

TitleColor

Die Farbe für Titel (wie sie durch die Verwendung des Pakets „titlesec“ konfiguriert wird).

Standard: {rgb}{0.126,0.263,0.361}

InnerLinkColor

Eine Farbe, die an hyperref als Wert für linkcolor und citecolor übergeben wird.

Standard: {rgb}{0.208,0.374,0.486}.

OuterLinkColor

Eine Farbe, die an hyperref als Wert für filecolor, menucolor und urlcolor übergeben wird.

Standard: {rgb}{0.216,0.439,0.388}

VerbatimColor

Die Hintergrundfarbe für code-blocks.

Standard: {RGB}{242,242,242} (entspricht {gray}{0.95}).

Geändert in Version 6.0.0: Zuvor war es {rgb}{1,1,1} (weiß).

VerbatimBorderColor

Die Rahmenfarbe.

Standard: {RGB}{32,32,32}

Geändert in Version 6.0.0: Zuvor war es {rgb}{0,0,0} (schwarz).

VerbatimHighlightColor

Die Farbe für hervorgehobene Zeilen.

Standard: {rgb}{0.878,1,1}

Hinzugefügt in Version 1.6.6.

TableRowColorHeader

Setzt die Hintergrundfarbe für (alle) Kopfzeilen von Tabellen.

Dies hat nur dann eine Wirkung, wenn entweder der latex_table_style 'colorrows' enthält oder wenn der Tabelle die Klasse colorrows zugewiesen ist. Sie wird für Tabellen mit der Klasse nocolorrows ignoriert.

Wie bei den anderen 'sphinxsetup'-Schlüsseln kann dies auch über einen LaTeX-Befehl \sphinxsetup{...} gesetzt oder geändert werden, der über die raw-Direktive eingefügt wird, oder auch aus einer LaTeX-Umgebung, die einer Container-Klasse zugeordnet ist und ein solches \sphinxsetup{...} verwendet.

Standard: {gray}{0.86}

Es gibt auch TableMergeColorHeader. Wenn verwendet, setzt dies eine spezifische Farbe für zusammengeführte einzeilige Zellen im Header.

Hinzugefügt in Version 5.3.0.

TableRowColorOdd

Setzt die Hintergrundfarbe für ungerade Zeilen in Tabellen (die Zeilenzählung beginnt bei 1 bei der ersten Nicht-Kopfzeile). Hat nur dann eine Wirkung, wenn der latex_table_style 'colorrows' enthält oder für bestimmte Tabellen die Klasse colorrows zugewiesen ist.

Standard: {gray}{0.92}

Es gibt auch TableMergeColorOdd.

Hinzugefügt in Version 5.3.0.

TableRowColorEven

Setzt die Hintergrundfarbe für gerade Zeilen in Tabellen.

Standard {gray}{0.98}

Es gibt auch TableMergeColorEven.

Hinzugefügt in Version 5.3.0.

verbatimsep

Der Abstand zwischen Codezeilen und dem Rahmen.

Siehe Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel für Alias pre_padding und zusätzliche Schlüssel.

Standard: \fboxsep

verbatimborder

Die Breite des Rahmens um code-blocks. Siehe auch Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel für pre_border-width.

Standard: \fboxrule

Wichtig

Seit 8.1.0 ist es möglich, die Direktiven topic, contents und sidebar separat zu gestalten, und ihre Standardwerte unterscheiden sich. Siehe Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel. Die nächsten drei Schlüssel werden als Legacy-Schnittstelle beibehalten, die nicht zwischen den drei Direktiven unterscheidet.

shadowsep

Diese Legacy-Option setzt den Abstand (in allen Richtungen gleich) gleichzeitig für die Direktiven topic, contents und sidebar.

shadowsize

Diese Legacy-Option setzt die Schattenbreite gleichzeitig für die Direktiven topic, contents und sidebar.

shadowrule

Diese Legacy-Option setzt die Rahmenbreite (auf allen Seiten gleich) gleichzeitig für die Direktiven topic, contents und sidebar.

Wichtig

Bei 7.4.0 verwenden alle Admonitions (nicht nur danger-type) die Möglichkeiten, die bei 5.1.0 und 6.2.0 hinzugefügt wurden. Alle Standardwerte haben sich geändert.

iconpackage

Der Name des LaTeX-Pakets, das für die Darstellung von Icons in den Admonition-Titeln verwendet wird. Sein Standardwert wird dynamisch auf fontawesome7, fontawesome6, fontawesome5, fontawesome oder none gesetzt, in absteigender Reihenfolge der Priorität und je nachdem, ob Pakete mit diesen Namen in der verwendeten LaTeX-Installation vorhanden sind. Der LaTeX-Code für jedes Admonition-Icon verwendet den Befehl \faIcon, wenn mit fontawesome{5,6,7} und \faicon, wenn mit fontawesome. Wenn kein „Font Awesome“-bezogenes Paket gefunden wird (oder wenn die Option erzwungen auf none gesetzt ist), werden die Icons stillschweigend entfernt. Benutzer können diese Option auf ein bestimmtes Paket setzen und müssen dann die div.note_title-icon und ähnliche Schlüssel konfigurieren, um dann die LaTeX-Schnittstelle dieses Pakets zu verwenden (siehe den Abschnitt Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel dazu).

Hinzugefügt in Version 7.4.0.

noteBorderColor, hintBorderColor, importantBorderColor, tipBorderColor

Die Farbe für den Admonition-Rand.

Standard: {RGB}{134,152,155}.

Geändert in Version 7.4.0.

noteBgColor, hintBgColor, importantBgColor, tipBgColor

Die Farbe für den Admonition-Hintergrund.

Standard: {RGB}{247,247,247}.

Hinzugefügt in Version 6.2.0.

Geändert in Version 7.4.0.

noteTextColor, hintTextColor, importantTextColor, tipTextColor

Die Farbe für den Admonition-Inhalt.

Standard: nicht gesetzt (Inhaltstext verwendet die Umgebungsschriftfarbe, a priori schwarz)

Hinzugefügt in Version 6.2.0: Dies gilt als experimentell bis 7.0.0. Diese Optionen haben Aliase div.note_TeXcolor (usw.), die in Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel beschrieben sind. Die Verwendung der letzteren bewirkt, dass Sphinx zu einem komplexeren LaTeX-Code wechselt, der die unter Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel beschriebene Anpassbarkeit unterstützt.

noteTeXextras, hintTeXextras, importantTeXextras, tipTeXextras

Zusätzlicher LaTeX-Code (wie \bfseries oder \footnotesize), der am Anfang des Inhalts ausgeführt wird.

Standard: leer

Hinzugefügt in Version 6.2.0: Dies gilt als experimentell bis 7.0.0. Diese Optionen haben Aliase div.note_TeXextras (usw.), die in Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel beschrieben sind.

noteborder, hintborder, importantborder, tipborder

Die Breite des Rahmens. Siehe Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel für Schlüssel, mit denen die Breite jedes Rahmens separat konfiguriert werden kann.

Standard: 0.5pt

warningBorderColor, cautionBorderColor, attentionBorderColor, dangerBorderColor, errorBorderColor

Die Farbe für den Admonition-Rand.

Standard: {RGB}{148,0,0}, außer für error, das red verwendet.

Geändert in Version 7.4.0.

warningBgColor, cautionBgColor, attentionBgColor, dangerBgColor, errorBgColor

Die Hintergrundfarbe für den Admonition-Hintergrund.

Standard: {RGB}{247,247,247}.

Geändert in Version 7.4.0.

warningborder, cautionborder, attentionborder, dangerborder, errorborder

Die Breite des Admonition-Rahmens. Siehe Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel für Schlüssel, mit denen die Breite jedes Rahmens separat konfiguriert werden kann.

Standard: 1pt, außer für error, das 1.25pt verwendet.

Geändert in Version 7.4.0.

AtStartFootnote

LaTeX-Makros, die am Anfang des Fußnotentextes am Seitenende, nach der Fußnotennummer, eingefügt werden.

Standard: \mbox{ }

BeforeFootnote

LaTeX-Makros, die vor dem Fußnoten-Zeichen eingefügt werden. Der Standardwert entfernt möglichen Leerraum davor (andernfalls könnte TeX dort einen Zeilenumbruch einfügen).

Standard: \leavevmode\unskip

Hinzugefügt in Version 1.5.

HeaderFamily

Standard \sffamily\bfseries. Setzt die für Überschriften verwendete Schriftart.

Zusätzliche CSS-ähnliche 'sphinxsetup' Schlüssel

Hinzugefügt in Version 5.1.0: Für code-block, topic und contents Direktive sowie stark typisierte Admonitions (warning, error, …).

Hinzugefügt in Version 6.2.0: Auch die Admonitions note, hint, important und tip können auf diese Weise gestylt werden. Die Verwendung eines der aufgelisteten Optionen für diese bewirkt die Verwendung eines komplexeren LaTeX-Codes als der standardmäßig verwendete (sphinxheavybox vs sphinxlightbox). Das Setzen von noteBgColor (oder hintBgColor, …) löst ebenfalls die Verwendung von sphinxheavybox für note (oder hint, …) aus.

Hinzugefügt in Version 7.4.0: Für *alle* Admonition-Typen setzt die Standardkonfiguration eine Hintergrundfarbe (daher wird immer das aufwändigere sphinxheavybox verwendet).

Wichtig

Weiterhin werden alle Admonition-Titel standardmäßig mit einer farbigen Zeile und einem Icon gestaltet, die dem aktuellen Rendering der Sphinx-eigenen Dokumente unter https://sphinx-doc.de nachempfunden sind. CSS-ähnliche Schlüssel werden hinzugefügt, um die Vordergrund- und Hintergrundfarben für den Titel sowie den LaTeX-Code für das Icon zu setzen.

Hinzugefügt in Version 7.4.0: Anpassbarkeit der Direktiven seealso und todo.

Hinzugefügt in Version 8.1.0: Separate Anpassbarkeit und neue Standardwerte für die Direktiven topic, contents und sidebar.

Vielleicht werden in Zukunft diese neuen Einstellungen von 5.1.0 (und 6.2.0) optional aus einer externen CSS-Datei importiert, aber derzeit müssen sie über die 'sphinxsetup'-Schnittstelle (oder den \sphinxsetup LaTeX-Befehl, der über die raw-Direktive eingefügt wird) verwendet werden, und die CSS-Syntax wird nur nachgeahmt.

Wichtig

Auf niedriger Ebene auftretende LaTeX-Fehler, die zu einem Build-Fehler führen, können auftreten, wenn die Eingabesyntax nicht beachtet wird.

• Insbesondere Farben müssen wie für die anderen zuvor beschriebenen farbbezogenen Optionen eingegeben werden, d.h. entweder in der \definecolor-Syntax oder über die \colorlet-Syntax.

  ...<other options>
  div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax
  div.error_background-TeXcolor=red!10,%     \colorlet syntax
  ...<other options>
  

• Ein Doppelpunkt anstelle des Gleichheitszeichens führt zu einem Fehler in LaTeX.

• ...border-width oder ...padding erwarten eine *einzelne* Dimension: Sie können bisher nicht mit leerzeichengetrennten Dimensionen verwendet werden.

• ...top-right-radius und ähnliche Werte können entweder eine einzelne oder *zwei* leerzeichengetrennte Dimensionen sein.

• Dimensionsspezifikationen müssen TeX-Einheiten wie pt, cm oder in verwenden. Die Einheit px wird von pdflatex und lualatex erkannt, aber nicht von xelatex oder platex.

• Es ist erlaubt, dass solche Spezifikationen sogenannte „dimensionsausdrücke“ sind, z.B. \fboxsep+2pt oder 0.5\baselineskip sind gültige Eingaben. Die Ausdrücke werden erst zur Setzzeit ausgewertet. Seien Sie jedoch vorsichtig, wenn Sie wie in diesen Beispielen TeX-Steuerbefehle verwenden, um den Backslash zu verdoppeln oder einen rohen Python-String für den Wert des Schlüssels ‘sphinxsetup’ zu verwenden.

• Vermeiden Sie generell das Einfügen unnötiger Leerzeichen in die Schlüsselwerte: Insbesondere bei Radien bricht eine Eingabe wie 2 pt 3pt LaTeX. Beachten Sie auch, dass \fboxsep \fboxsep in LaTeX nicht als leerzeichengetrennt angesehen wird. Sie müssen etwas wie {\fboxsep} \fboxsep verwenden. Oder verwenden Sie direkt 3pt 3pt, was a priori äquivalent und einfacher ist.

Die Optionen sind alle nach einem ähnlichen Muster benannt, das von einem prefix abhängt, gefolgt von einem Unterstrich und dann dem Eigenschaftsnamen.

Direktive	Optionspräfix	LaTeX-Umgebung
code-block	pre	sphinxVerbatim
literalinclude	pre	sphinxVerbatim
topic	div.topic	sphinxtopic
contents	div.contents	sphinxcontents
sidebar	div.sidebar	sphinxsidebar
note	div.note	sphinxnote
warning	div.warning	sphinxwarning
weitere Admonition-Typen <type>	div.<type>	sphinx<type>
seealso	div.seealso	sphinxseealso
todo	div.todo	sphinxtodo

Hier sind nun diese Optionen sowie ihre gemeinsamen Standardwerte. Ersetzen Sie unten <prefix> durch das tatsächliche Präfix, wie oben erklärt. Vergessen Sie nicht den Unterstrich, der das Präfix von den Eigenschaftsnamen trennt.

• <prefix>_border-top-width,

  <prefix>_border-right-width,

  <prefix>_border-bottom-width,

  <prefix>_border-left-width,

  <prefix>_border-width. Letzteres kann (derzeit) nur eine *einzelne* Dimension sein, die dann alle vier anderen setzt.

  Standardmäßig sind all diese Dimensionen gleich. Sie sind gesetzt auf

  • 0.4pt für code-block,

  • 0.5pt für die Direktiven topic und contents,

  • 1pt für die Direktive sidebar,

  • 0.5pt für note und andere „leichte“ Admonitionen,

  • 0.5pt für die Direktiven seealso und todo,

  • 1pt für warning und andere „starke“ Admonitionen außer error, die 1.25pt verwendet.

  Geändert in Version 7.4.0: Geänderte Standardwerte für topic und error.

  Geändert in Version 8.1.0: Abweichend von topic-Standardwerten für sidebar.

• <prefix>_box-decoration-break kann entweder auf clone oder slice gesetzt werden und konfiguriert das Verhalten bei Seitenumbrüchen. Es ist standardmäßig auf slice für code-block (d.h. für <prefix>=pre) seit 6.0.0. Für andere Direktiven ist der Standardwert clone.

• <prefix>_padding-top,

  <prefix>_padding-right,

  <prefix>_padding-bottom,

  <prefix>_padding-left,

  <prefix>_padding. Letzteres kann (derzeit) nur eine *einzelne* Dimension sein, die dann alle vier anderen setzt.

  Die Standardwerte

  • alle vier 3pt für code-block,

  • 6pt, 7pt, 6pt, 7pt für topic,

  • 10pt, 7pt, 12pt, 7pt für contents,

  • 6pt, 5.5pt, 6pt, 5.5pt für sidebar,

  • 6pt, 7pt, 6pt, 7pt für alle „leichten“ Admonitionen sowie die Direktiven seealso und todo.

  • 6pt, 6.5pt, 6pt, 6.5pt für die starken Admonitionstypen außer error, das einen horizontalen Abstand von 6.25pt verwendet.

  Geändert in Version 7.4.0: Alle Standardwerte wurden geändert, außer für code-block. Admonitionen sind so eingerichtet, dass linker (oder rechter) Padding plus linker (oder rechter) Rahmenbreite immer 7.5pt ergeben, sodass Inhalte auf derselben Seite in PDF gut vertikal übereinstimmen. Dies ist nur eine Eigenschaft der Standardwerte, keine Einschränkung möglicher Benutzerauswahlen.

  Geändert in Version 8.1.0: Separate Standardwerte für topic, contents und sidebar.

• <prefix>_border-top-left-radius,

  <prefix>_border-top-right-radius,

  <prefix>_border-bottom-right-radius,

  <prefix>_border-bottom-left-radius,

  <prefix>_border-radius. Dieser letzte Schlüssel setzt die ersten vier auf seinen zugewiesenen Wert. Jeder Schlüsselwert kann entweder eine einzelne oder *zwei* Dimensionen sein, die dann leerzeichengetrennt sind.

  Die Standardwerte

  • 3pt für code-block (seit 6.0.0) und alle Ecken,

  • 8pt für alle Ecken von topic,

  • 12pt für die untere rechte Ecke von contents, andere verwenden 0pt,

  • 12pt für die obere linke und untere rechte Ecke von sidebar, 0pt für oben rechts und unten links.

  • alle Radien auf 5pt für note, hint und tip gesetzt,

  • 0pt, d.h. gerade Ecken für alle anderen Direktiven.

  Geändert in Version 7.4.0: topic und note-ähnliche Admonitionen erhalten (mindestens) abgerundete Ecken.

  Geändert in Version 8.1.0: Separate Standardwerte für topic, contents und sidebar.

  Siehe oben eine Bemerkung über Fallstricke mit Leerzeichen in LaTeX.

• <prefix>_box-shadow ist insofern besonders, als er sein kann

  • das Schlüsselwort none,

  • oder eine einzelne Dimension (die sowohl den x-Offset als auch den y-Offset angibt),

  • oder zwei Dimensionen (leerzeichengetrennt),

  • oder zwei Dimensionen gefolgt vom Schlüsselwort inset.

  Der x-Offset und y-Offset können negativ sein. Ein negativer x-Offset bedeutet, dass der Schatten links liegt. Der Schatten erstreckt sich in den Seitenrand, unabhängig davon, ob der Offset positiv oder negativ ist.

  Standardmäßig ist dies none, *außer* für die Direktive contents, die 4pt 4pt verwendet.

  Geändert in Version 8.1.0: Standardmäßig kein Schatten für topic und sidebar.

• <prefix>_border-TeXcolor,

  <prefix>_background-TeXcolor,

  <prefix>_box-shadow-TeXcolor,

  <prefix>_TeXcolor. Dies sind Farben.

  Seit 6.0.0 sind die Rahmen- und Hintergrundfarben von code-block standardmäßig {RGB}{32,32,32} (d.h. {HTML}{202020}) bzw. {RGB}{242,242,242} (d.h. {gray}{0.95} oder {HTML}{F2F2F2}).

  Bei 7.4.0 erhalten andere Direktiven nicht-schwarze/weiße Standardrahmen- und Hintergrundfarben. Hier verwenden sie die hexadezimale Notation von xcolor (die immer 6 Hexadezimalziffern erfordert)

  • {HTML}{F7F7F7} dient als Hintergrundfarbe für alle.

  • {HTML}{86989B} ist die Rahmenfarbe von leichten Admonitionen (einschließlich seealso und todo) sowie von topic, contents und sidebar Direktiven.

  • {HTML}{940000} ist die Rahmenfarbe von warning-Typ Admonitionen, außer error, das {HTML}{B40000} verwendet.

  Die einzigen Direktiven, die standardmäßig einen Schatten anzeigen, sind contents und sidebar. Die Schattenfarbe für ersteres ist {HTML}{6C6C6C} und für letzteres {HTML}{9EACAF}.

  Die <prefix>_TeXcolor steht für die CSS-Eigenschaft „color“, d.h. sie beeinflusst die Textfarbe des Inhalts. Wie bei den drei anderen Optionen ist die Benennung TeXcolor dazu da, hervorzuheben, dass die Eingabesyntax die TeX-Syntax für Farben ist und nicht eine HTML/CSS-Syntax. Wenn das Paket xcolor in der LaTeX-Installation verfügbar ist, können benannte Farben direkt als Schlüsselwerte verwendet werden. Erwägen Sie die Übergabe von Optionen wie dvipsnames, svgnames oder x11names an xcolor über den Schlüssel 'passoptionstopackages' von latex_elements.

  Wenn <prefix>_TeXcolor gesetzt ist, wird ein \color-Befehl am Anfang des Direktiveninhalts eingefügt; bei Admonitionen geschieht dies nach der Überschrift, die den Admonitionstyp wiedergibt.

• <prefix>_TeXextras: Wenn gesetzt, muss sein Wert ein LaTeX-Befehl oder mehrere Befehle sein, z.B. \itshape. Diese Befehle werden am Anfang des Inhalts eingefügt; bei Admonitionen geschieht dies nach der Überschrift, die den Admonitionstyp wiedergibt.

Die folgenden Schlüssel für Admonitionen, topic, contents und sidebar, wurden alle bei 7.4.0 (und 8.1.0 für die letzteren drei) hinzugefügt.

• div.<type>_title-background-TeXcolor: die Hintergrundfarbe für den Titel.

  Wichtig

  Die farbige Titelleiste wird als Ergebnis der Standarddefinitionen von Sphinx für die verschiedenen \sphinxstyle<type>title-Befehle erzeugt, die den LaTeX-Befehl \sphinxdotitlerow verwenden. Siehe Makros.

• div.<type>_title-foreground-TeXcolor: die Farbe, die für das Symbol verwendet werden soll (sie gilt nur für das Symbol, nicht für den Titel der Admonition).

• div.<type>_title-icon: der LaTeX-Code, der für die Erzeugung des Symbols für den gegebenen <admonition type> verantwortlich ist. Zum Beispiel ist der Standard für note div.note_title-icon=\faIcon{info-circle} mit fontawesome5, aber div.note_title-icon=\faIcon{circle-info} mit fontawesome6 und fontawesome7. Wenn Sie die von Sphinx verwendeten Symbole ändern möchten, verwenden Sie in diesen Schlüsseln den LaTeX-Befehl \faIcon, wenn fontawesome5, 6 oder 7 in Ihrer LaTeX-Installation vorhanden ist. Wenn Ihr System nur das Paket fontawesome bereitstellt, verwenden Sie dessen Befehl \faicon (nicht \faIcon), um die Auswahl der Symbole zu ändern. Der Schlüssel iconpackage von 'sphinxsetup' kann verwendet werden, um die Verwendung eines aus fontawesome{,5,6,7} zu erzwingen oder der Name eines anderen symbolgebenden Pakets zu sein. In letzterem Fall müssen Sie die Schlüssel div.<type>_title-icon so konfigurieren, dass sie die für dieses benutzerdefinierte Symbolpaket geeigneten LaTeX-Befehle verwenden.

Hinweis

• Alle Direktiven unterstützen box-decoration-break, um auf slice gesetzt zu werden.

  Geändert in Version 6.2.0: Früher nur code-block. Der Standardwert bleibt clone für alle anderen Direktiven, aber dies wird sich wahrscheinlich mit 7.0.0 ändern.

• Die Ecken abgerundeter Boxen können elliptisch sein.

  Geändert in Version 6.2.0: Früher wurden nur kreisförmige abgerundete Ecken unterstützt und eine abgerundete Ecke zwang den gesamten Rahmen, die gleiche konstante Breite von <prefix>_border-width zu verwenden.

• Innenliegende Schatten sind mit abgerundeten Ecken inkompatibel. Wenn beide angegeben sind, wird der innenliegende Schatten einfach ignoriert.

  Geändert in Version 6.2.0: Früher war es umgekehrt, die abgerundeten Ecken wurden ignoriert, wenn ein innenliegender Schatten angegeben war.

• <prefix>_TeXcolor und <prefix>_TeXextras sind neu seit 6.2.0.

  Der Nutzen ist im Fall von code-block zweifelhaft

  • pre_TeXcolor beeinflusst nur wenige Nicht-Pygments-Tokens; es färbt zwar die Zeilennummern, aber wenn man *nur* diese färben möchte, muss man über die fancyvrb-Schnittstelle gehen.

  • pre_TeXextras=\footnotesize (als Beispiel) ist äquivalent zur Einstellung des Schlüssels 'fvset' auf r'\fvset{fontsize=\footnotesize}'.

  Betrachten Sie diese Optionen als experimentell und bedenken Sie, dass sich einige Implementierungsdetails ändern können. Zum Beispiel, wenn die pre_TeXextras LaTeX-Befehle von Sphinx an einen anderen Ort platziert würden, könnten sie den 'fvset'-Effekt überschreiben, vielleicht wird dies in einer zukünftigen Version geschehen.

• Abgerundete Boxen werden über die pict2e-Schnittstelle zu grundlegenden PDF-Grafikoperationen realisiert. Wenn dieses LaTeX-Paket nicht gefunden werden kann, wird der Build fortgesetzt und alle Boxen mit geraden Ecken gerendert.

• Elliptische Ecken verwenden das LaTeX-Paket ellipse, das pict2e erweitert. Wenn dieses LaTeX-Paket nicht gefunden werden kann, werden abgerundete Ecken als Kreisbögen (oder gerade, wenn pict2e nicht verfügbar ist) gerendert.

Das folgende ältere Verhalten gilt

• Für code-block oder literalinclude gehen Padding und Rahmenbreite sowie Schatten (falls vorhanden) in den Rand; die Codezeilen bleiben unabhängig von den Werten des Paddings und der Rahmenbreite an derselben Stelle, abgesehen von der vertikalen Verschiebung, um kein anderes Text zu überschreiben, aufgrund der Breite des Rahmens oder des externen Schattens.

• Für die anderen Direktiven erstrecken sich Schatten horizontal in die Seitenränder, aber der Rahmen und das zusätzliche Padding bleiben innerhalb des Textbereichs.

• code-block und literalinclude verwenden die gleiche LaTeX-Umgebung und Befehle und sind nicht separat anpassbar.

LaTeX-Makros und Umgebungen

Die „LaTeX-Paket“-Datei sphinx.sty lädt verschiedene Komponenten, die Unterstützungsmakros (auch Befehle genannt) und Umgebungen bereitstellen, welche im Markup verwendet werden, das vom latex-Builder ausgegeben und dann über die LaTeX-Toolchain zu pdf konvertiert wird. Auch die „LaTeX-Klassen“-Dateien sphinxhowto.cls und sphinxmanual.cls definieren oder passen einige Umgebungen an. Alle diese Dateien befinden sich im LaTeX-Build-Verzeichnis.

Einige davon bieten Funktionen, die von vorhandenen LaTeX-Paketen nicht verfügbar sind, und umgehen LaTeX-Beschränkungen bei Listen, Tabellenzellen, Verbatim-Rendering, Fußnoten usw.

Andere definieren einfach Makros mit öffentlichen Namen, um ihre Standardwerte durch benutzerdefinierte Inhalte in der Präambel leicht überschreiben zu können. Wir werden die meisten dieser öffentlichen Namen hier überprüfen, aber die Standardwerte müssen in ihren jeweiligen Definitionsdateien nachgeschlagen werden.

Hinweis

Der Sphinx-LaTeX-Supportcode ist in mehrere kleinere Dateien aufgeteilt. Anstatt Code über latex_elements['preamble'] zur Präambel hinzuzufügen, ist es auch möglich, eine der Komponentendateien des Sphinx-LaTeX-Codes vollständig durch eine benutzerdefinierte Version zu ersetzen, indem einfach eine modifizierte Kopie in das Projektverzeichnis aufgenommen und der Dateiname zur Liste latex_additional_files hinzugefügt wird. Überprüfen Sie das LaTeX-Build-Verzeichnis auf die Dateinamen und Inhalte.

Geändert in Version 4.0.0: Aufteilung von sphinx.sty in mehrere kleinere Einheiten, um die gleichzeitige Anpassung vieler Aspekte zu erleichtern.

Makros

• Textformatierungsbefehle

  Name, bildet Argument #1 ab auf:
  \sphinxstrong	\textbf{#1}
  \sphinxcode	\texttt{#1}
  \sphinxbfcode	\textbf{\sphinxcode{#1}}
  \sphinxemail	\textsf{#1}
  \sphinxtablecontinued	\textsf{#1}
  \sphinxtitleref	\emph{#1}
  \sphinxmenuselection	\emph{#1}
  \sphinxguilabel	\emph{#1}
  \sphinxkeyboard	\sphinxcode{#1}
  \sphinxaccelerator	\underline{#1}
  \sphinxcrossref	\emph{#1}
  \sphinxtermref	\emph{#1}
  \sphinxsamedocref	\emph{#1}
  \sphinxparam	\emph{#1}
  \sphinxtypeparam	\emph{#1}
  \sphinxoptional	[#1] mit größeren Klammern, siehe Quelle

  Hinzugefügt in Version 1.4.5: Verwendung von Makronamen mit Präfix \sphinx, um die Wahrscheinlichkeit von Konflikten mit LaTeX-Paketen zu begrenzen.

  Hinzugefügt in Version 1.8: \sphinxguilabel

  Hinzugefügt in Version 3.0: \sphinxkeyboard

  Hinzugefügt in Version 6.2.0: \sphinxparam, \sphinxsamedocref

  Hinzugefügt in Version 7.1.0: \sphinxparamcomma, das standardmäßig ein Komma gefolgt von einem Leerzeichen und \sphinxparamcommaoneperline ist. Es wird für Signaturen mit einem Parameter pro Zeile verwendet (siehe maximum_signature_line_length) und ist standardmäßig \texttt{,}.

  Signaturen von Python-Funktionen werden als name<leerzeichen>(parameter) oder name<leerzeichen>[typ parameter]<leerzeichen>(parameter) (siehe PEP 695) gerendert, wobei die Länge von <leerzeichen> standardmäßig auf 0pt gesetzt ist. Dies kann z.B. über \setlength{\sphinxsignaturelistskip}{1ex} geändert werden.

• Weitere Textformatierung

  Name, bildet Argument #1 ab auf:
  \sphinxstyleindexentry	\texttt{#1}
  \sphinxstyleindexextra	(\emph{#1}) (mit einem vorangestellten Leerzeichen)
  \sphinxstyleindexpageref	, \pageref{#1}
  \sphinxstyleindexpagemain	\textbf{#1}
  \sphinxstyleindexlettergroup	{\Large\sffamily#1}\nopagebreak\vspace{1mm}
  \sphinxstyleindexlettergroupDefault	Quelle prüfen, zu lang für hier
  \sphinxstyletopictitle	\textbf{#1}\par\medskip
  \sphinxstylesidebartitle	\textbf{#1}\par\medskip
  \sphinxstyleothertitle	\textbf{#1}
  \sphinxstylesidebarsubtitle	~\\\textbf{#1} \smallskip
  \sphinxstyletheadfamily	\sffamily (dieser hat kein Argument)
  \sphinxstyleemphasis	\emph{#1}
  \sphinxstyleliteralemphasis	\emph{\sphinxcode{#1}}
  \sphinxstylestrong	\textbf{#1}
  \sphinxstyleliteralstrong	\sphinxbfcode{#1}
  \sphinxstyleabbreviation	\textsc{#1}
  \sphinxstyleliteralintitle	\sphinxcode{#1}
  \sphinxstylecodecontinued	{\footnotesize(#1)}}
  \sphinxstylecodecontinues	{\footnotesize(#1)}}
  \sphinxstylenotetitle	\sphinxdotitlerow{note}{#1}
  \sphinxstylehinttitle	\sphinxdotitlerow{hint}{#1}
  \sphinxstyleimportanttitle	\sphinxdotitlerow{important}{#1}
  \sphinxstyletiptitle	\sphinxdotitlerow{tip}{#1}
  \sphinxstylewarningtitle	\sphinxdotitlerow{warning}{#1}
  \sphinxstylecautiontitle	\sphinxdotitlerow{caution}{#1}
  \sphinxstyleattentiontitle	\sphinxdotitlerow{attention}{#1}
  \sphinxstyledangertitle	\sphinxdotitlerow{danger}{#1}
  \sphinxstyleerrortitle	\sphinxdotitlerow{error}{#1}
  \sphinxstyleseealsotitle	\sphinxdotitlerow{seealso}{#1}
  \sphinxstyletodotitle	\sphinxdotitlerow{todo}{#1}
  \sphinxstyletopictitle	\sphinxdotitlerow{topic}{#1}
  \sphinxstylecontentstitle	\sphinxdotitlerow{contents}{#1}
  \sphinxstylesidebartitle	\sphinxdotitlerow{sidebar}{#1}

  Hinweis

  Damit diese Tabelle in PDF-Ausgabe auf die Seitenbreite passt, haben wir ein wenig gelogen. Zum Beispiel ist die tatsächliche Definition von \sphinxstylenotetitle

  \newcommand\sphinxstylenotetitle[1]%
  {\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}}
  

  Die gleiche Bemerkung gilt für alle anderen ähnlichen Befehle, die mit Ermahnungen verbunden sind. Die topic, contents und sidebar verwenden kein \sphinxremovefinalcolon, da sie es nicht benötigen.

  Hinzugefügt in Version 1.5: Diese Makros waren früher fest codiert als nicht anpassbare \texttt, \emph, usw.

  Hinzugefügt in Version 1.6: \sphinxstyletheadfamily, das standardmäßig auf \sffamily gesetzt ist und mehrere Absätze in Kopfzeilen von Tabellen erlaubt.

  Hinzugefügt in Version 1.6.3: \sphinxstylecodecontinued und \sphinxstylecodecontinues.

  Hinzugefügt in Version 1.8: \sphinxstyleindexlettergroup, \sphinxstyleindexlettergroupDefault.

  Hinzugefügt in Version 6.2.0: \sphinxstylenotetitle und andere. Das #1 ist der lokalisierte Name der Direktive, mit einem abschließenden Doppelpunkt. Umschließen Sie es mit \sphinxremovefinalcolon{#1}, wenn dieser abschließende Doppelpunkt entfernt werden soll.

  Hinzugefügt in Version 7.4.0: Das LaTeX-Kommando \sphinxdotitlerowwithicon wurde hinzugefügt.

  Geändert in Version 8.1.0: \sphinxdotitlerowwithicon erkennt nun automatisch, ob ein Symbol mit dem als erstes Argument verwendeten gerenderten Element verbunden ist oder nicht.

  Hinzugefügt in Version 8.1.0: \sphinxdotitlerow als Alias für \sphinxdotitlerowwithicon.

  Hinzugefügt in Version 8.1.0: Titel der Direktiven topic, contents und sidebar werden ebenfalls mit \sphinxdotitlerow gestylt (sie haben keine zugeordneten Standard-Symbole).

• \sphinxtableofcontents: Ein Wrapper (unterschiedlich definiert in sphinxhowto.cls und sphinxmanual.cls) des Standard-\tableofcontents. Das Makro \sphinxtableofcontentshook wird während seiner Expansion direkt vor \tableofcontents selbst ausgeführt.

  Geändert in Version 1.5: Früher wurde die Bedeutung von \tableofcontents von Sphinx modifiziert.

  Geändert in Version 2.0: Fest codierte Neudefinitionen von \l@section und \l@subsection, die früher beim Laden der Dokumentenklasse 'manual' ausgeführt wurden, werden jetzt später über \sphinxtableofcontentshook ausgeführt. Dieses Makro wird auch von der Dokumentenklasse 'howto' ausgeführt, ist aber bei dieser standardmäßig leer.

  Hinweis

  Wenn Sie beim Hinzufügen des tocloft Pakets in die Präambel geladen wird, fügen Sie auch \renewcommand\sphinxtableofcontentshook{} zur Präambel hinzu, da es sonst \l@section und \l@subsection zurücksetzt und die tocloft-Anpassung aufhebt.

• \sphinxmaketitle: Wird als Standardeinstellung für den 'maketitle' Schlüssel in latex_elements verwendet. Definiert in den Klassendateien sphinxmanual.cls und sphinxhowto.cls.

  Geändert in Version 1.8.3: Früher wurde \maketitle aus der LaTeX-Dokumentenklasse von Sphinx modifiziert.

• \sphinxbackoftitlepage: Für die Dokumentenklasse 'manual' und wenn sie definiert ist, wird sie am Ende von \sphinxmaketitle ausgeführt, vor dem endgültigen \clearpage. Verwenden Sie entweder den Schlüssel 'maketitle' oder den Schlüssel 'preamble' von latex_elements, um eine benutzerdefinierte Definition von \sphinxbackoftitlepage hinzuzufügen.

  Hinzugefügt in Version 1.8.3.

• \sphinxcite: Ein Wrapper des Standard-\cite für Zitatreferenzen.

Der Befehl \sphinxbox

Hinzugefügt in Version 6.2.0.

Der Befehl \sphinxbox[key=value,...]{inline text} kann verwendet werden, um Inline-Textelemente mit all den Anpassungsmöglichkeiten zu "verpacken", die in Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel beschrieben wurden. Es handelt sich um einen LaTeX-Befehl mit einem optionalen Argument, das eine durch Kommas getrennte Liste von Schlüssel=Wert-Paaren ist, wie bei Die Sphinxsetup-Konfigurationseinstellung. Hier ist die vollständige Liste der Schlüssel. Sie verwenden kein Präfix.

• border-width,

• border-top-width, border-right-width, border-bottom-width, border-left-width,

• padding,

• padding-top, padding-right, padding-bottom, padding-left,

• border-radius,

• border-top-left-radius, border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius,

• box-shadow,

• border-TeXcolor, background-TeXcolor, box-shadow-TeXcolor, TeXcolor,

• TeXextras,

• und addstrut, was ein boolescher Schlüssel ist, d. h. zur Verwendung als addstrut=true, oder addstrut allein, wobei =true weggelassen wird, oder addstrut=false.

Dieser letzte Schlüssel ist spezifisch für \sphinxbox und bedeutet, ein \strut hinzuzufügen, damit Höhen und Tiefen zwischen verschiedenen Instanzen in derselben Zeile mit unterschiedlichem Inhalt ausgeglichen werden. Der Standard ist addstrut=false. Die Kombination addstrut, padding-bottom=0pt, padding-top=1pt ist oft zufriedenstellend.

Beachten Sie Zusätzliche CSS-ähnliche 'sphinxsetup'-Schlüssel für wichtige Syntaxinformationen bezüglich der anderen Schlüssel. Die Standardkonfiguration verwendet keinen Schatten, eine Rahmenbreite von \fboxrule, einen Abstand von \fboxsep, abgerundete Ecken mit Radien von \fboxsep und Hintergrund- sowie Rahmenfarben wie bei der Standarddarstellung von Code-Blöcken.

Wenn eine Verwendung von \sphinxbox innerhalb einer anderen verschachtelt ist, ignoriert sie die Optionen der äußeren: Sie setzt zuerst alle Optionen auf ihren Standardzustand zurück, wie sie vor der Anwendung der äußeren Box-Optionen waren, und wendet dann ihre eigenen spezifischen an.

Man kann diese Standardwerte über den Befehl \sphinxboxsetup{key=value,...} ändern. Die Wirkung ist kumulativ, wenn dieser Befehl mehrmals verwendet wird. Hier sind die Optionen ein obligatorisches Argument und daher in geschweiften Klammern, nicht in eckigen.

Hier sind einige Anwendungsbeispiele

latex_elements = {
    'preamble': r'''
% modify globally the defaults
\sphinxboxsetup{border-width=2pt,%
                border-radius=4pt,%
                background-TeXcolor=yellow!20}
% configure some styling element with some extra specific options:
\protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
''',
}

Ein Dienstprogramm \newsphinxbox wird bereitgestellt, um ein neues Box-Makro zu erstellen, z. B. \foo, das genau wie \sphinxbox funktioniert, aber mit einer gegebenen zusätzlichen Konfiguration.

% the specific options to \foo are within brackets
\newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
% then use this \foo, possibly with some extra options still:
\protected\def\sphinxguilabel#1{\foo{#1}}
\protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}

Boxen, die mit \foo gerendert werden, gehorchen, wie die, die \sphinxbox direkt verwenden, der aktuellen Konfiguration, wie sie möglicherweise mitten im Dokument über \sphinxboxsetup (aus einem raw LaTeX-Markup) eingestellt wurde; der einzige Unterschied ist, dass sie eine anfängliche zusätzliche Reihe von Standard-Extras haben.

In den obigen Beispielen können Sie wahrscheinlich die \renewcommand-Syntax verwenden, wenn Sie sie \protected\def vorziehen (mit [1] anstelle von #1 dann).

Umgebungen

• Eine figure kann eine optionale Legende mit beliebigen Körper-Elementen haben: diese werden in einer sphinxlegend Umgebung gerendert. Die Standarddefinition gibt \small aus und endet mit \par.

  Hinzugefügt in Version 1.5.6: Früher war \small fest im LaTeX-Writer codiert und das abschließende \par fehlte.

• Umgebungen, die mit Ermahnungen verbunden sind

  • sphinxnote,

  • sphinxhint,

  • sphinximportant,

  • sphinxtip,

  • sphinxwarning,

  • sphinxcaution,

  • sphinxattention,

  • sphinxdanger,

  • sphinxerror.

  Diese können einzeln mit \renewenvironment neu definiert werden und müssen dann mit einem Argument definiert werden (es ist die Überschrift der Notiz, z. B. Warning: für die warning Direktive, wenn Englisch die Dokumentensprache ist). Ihre Standarddefinitionen verwenden entweder die Umgebungen sphinxheavybox (für die letzten 5) oder sphinxlightbox, die so konfiguriert sind, dass sie die Parameter (Farben, Rahmenstärke) verwenden, die für jeden Typ spezifisch sind und über den 'sphinxsetup'-String eingestellt werden können.

  Geändert in Version 1.5: Verwendung von öffentlichen Umgebungsnamen, separate Anpassbarkeit der Parameter, wie noteBorderColor, noteborder, warningBgColor, warningBorderColor, warningborder, ...

• Umgebung für die seealso Direktive: sphinxseealso. Sie nimmt ein Argument, das der lokalisierte String See also gefolgt von einem Doppelpunkt sein wird.

  Hinzugefügt in Version 6.1.0.

  Geändert in Version 6.2.0: Der Doppelpunkt ist nun Teil des Markups und wird nicht mehr von der Umgebung eingefügt, um Kohärenz mit der allgemeinen Behandlung von Ermahnungen zu gewährleisten.

• Umgebung für die todo Direktive: sphinxtodo. Sie nimmt ein Argument, nämlich die Lokalisierung von Todo (mit einem Doppelpunkt am Ende; die Standarddarstellung entfernt diesen Doppelpunkt und platziert den lokalisierten String in seiner eigenen farbigen Titelzeile).

  Hinzugefügt in Version 7.4.0.

• Die Direktiven topic, contents und sidebar sind jeweils mit den Umgebungen sphinxtopic, sphinxcontents und sphinxsidebar verbunden.

  Hinzugefügt in Version 1.4.2: Früherer Code wurde in eine Umgebung refaktorisiert, die Seitenumbrüche ermöglicht.

  Geändert in Version 1.5: Optionen shadowsep, shadowsize, shadowrule.

  Hinzugefügt in Version 8.1.0: Separate Umgebungen (alle drei Wrapper um sphinxShadowBox) und separate Anpassbarkeit.

• Die Literalblöcke (über :: oder code-block) und Literal-Includes (literalinclude) werden mit der Umgebung sphinxVerbatim implementiert, die ein Wrapper der Verbatim Umgebung aus dem Paket fancyvrb.sty ist. Sie fügt die Behandlung der oberen Bildunterschrift und das Umbrechen langer Zeilen hinzu, sowie einen Rahmen, der Seitenumbrüche ermöglicht. Innerhalb von Tabellen ist die verwendete Umgebung sphinxVerbatimintable (sie zeichnet keinen Rahmen, erlaubt aber eine Bildunterschrift).

  Geändert in Version 1.5: Verbatim behält die exakt gleiche Bedeutung wie in fancyvrb.sty (auch unter dem Namen OriginalVerbatim); sphinxVerbatimintable wird in Tabellen verwendet.

  Hinzugefügt in Version 1.5: Optionen verbatimwithframe, verbatimwrapslines, verbatimsep, verbatimborder.

  Hinzugefügt in Version 1.6.6: Unterstützung für die Option :emphasize-lines:

  Hinzugefügt in Version 1.6.6: Einfachere Anpassbarkeit der Formatierung durch für den Benutzer freigegebene LaTeX-Makros wie \sphinxVerbatimHighlightLine.

• Die Bibliographie verwendet sphinxthebibliography und der Python-Modul-Index sowie der allgemeine Index verwenden beide sphinxtheindex; diese Umgebungen sind Wrapper der thebibliography und der theindex Umgebungen, wie sie von der Dokumentenklasse (oder Paketen) bereitgestellt werden.

  Geändert in Version 1.5: Früher wurden die ursprünglichen Umgebungen von Sphinx modifiziert.

Verschiedenes

• Jeder Textabsatz im Dokumentkörper beginnt mit \sphinxAtStartPar. Derzeit wird dies verwendet, um einen horizontalen Skip mit Nullbreite einzufügen, was ein Trick ist, um die Silbentrennung des ersten Wortes eines Absatzes in einem schmalen Kontext (wie einer Tabellenzelle) durch TeX zu ermöglichen. Für 'lualatex', das den Trick nicht benötigt, tut \sphinxAtStartPar nichts.

  Hinzugefügt in Version 3.5.0.

• Die Überschriften von Abschnitten, Unterabschnitten usw. werden mit dem Befehl \titleformat von titlesec gesetzt.

• Für die Dokumentenklasse 'manual' können die Kapitelüberschriften mit den Befehlen \ChNameVar, \ChNumVar, \ChTitleVar von fncychap angepasst werden. Die Datei sphinx.sty enthält benutzerdefinierte Neudefinitionen für den Fall der fncychap-Option Bjarne.

  Geändert in Version 1.5: Früher war die Verwendung von fncychap mit anderen Stilen als Bjarne funktionsuntüchtig.

• Die role Direktive ermöglicht es, Inline-Text mit Klassenargumenten zu markieren. Dies wird in der LaTeX-Ausgabe über den Dispatcher-Befehl \DUrole behandelt wie in Docutils. Objekt-Signaturen verwenden ebenfalls \DUrole für einige Komponenten, mit ein- oder zweistelligen Klassennamen wie in der HTML-Ausgabe.

  Geändert in Version 8.1.0: Wenn mehrere Klassen über eine benutzerdefinierte Rolle injiziert werden, verwendet die LaTeX-Ausgabe verschachtelte \DUrole-Aufrufe, wie in der Docutils-Dokumentation. Zuvor wurde ein einzelnes \DUrole mit kommagetrennten Klassen verwendet, was die LaTeX-Anpassung erschwerte.

• Docutils container Direktiven werden in der LaTeX-Ausgabe unterstützt: damit eine Container-Klasse mit dem Namen foo das finale PDF über LaTeX beeinflussen kann, muss im Präambel eine Umgebung sphinxclassfoo definiert werden. Ein einfaches Beispiel wäre

  \newenvironment{sphinxclassred}{\color{red}}{}
  

  Derzeit müssen Klassennamen nur ASCII-Zeichen enthalten und Zeichen vermeiden, die für LaTeX speziell sind, wie \.

  Hinzugefügt in Version 4.1.0.

Hinweis

Als experimentelle Funktion kann Sphinx benutzerdefinierte Vorlagendateien für die LaTeX-Quelle verwenden, wenn Sie eine Datei namens _templates/latex.tex.jinja in Ihrem Projekt haben.

Zusätzliche Dateien longtable.tex.jinja, tabulary.tex.jinja und tabular.tex.jinja können zu _templates/ hinzugefügt werden, um einige Aspekte der Tabellendarstellung zu konfigurieren (wie die Position der Bildunterschrift).

Hinzugefügt in Version 1.6: Derzeit sind alle Vorlagenvariablen instabil und undokumentiert.

Geändert in Version 7.4: Unterstützung für die Dateiendung .jinja wurde hinzugefügt, die bevorzugt wird. Die alten Dateinamen bleiben unterstützt. (latex.tex_t, longtable.tex_t, tabulary.tex_t und tabular.tex_t)

Vorherige

Veraltete APIs

Nächste

Unterstützung erhalten