HTML-Themen

Sphinx bietet eine Reihe von Buildern für HTML und HTML-basierte Formate.

Builder

Themes

Hinzugefügt in Version 0.6.

Hinweis

Dieser Abschnitt enthält Informationen zur Verwendung bereits vorhandener HTML-Themes. Wenn Sie Ihr eigenes Theme erstellen möchten, lesen Sie Entwicklung von HTML-Themes.

Sphinx unterstützt die Änderung des Erscheinungsbilds seiner HTML-Ausgabe über Themes. Ein Theme ist eine Sammlung von HTML-Vorlagen, Stylesheets und anderen statischen Dateien. Zusätzlich verfügt es über eine Konfigurationsdatei, die angibt, von welchem Theme geerbt werden soll, welcher Hervorhebungsstil verwendet werden soll und welche Optionen zur Anpassung des Erscheinungsbilds des Themes verfügbar sind.

Themes sind darauf ausgelegt, projektunabhängig zu sein, sodass sie unverändert für verschiedene Projekte verwendet werden können.

Ein Theme verwenden

Die Verwendung eines mit Sphinx gelieferten Themes ist einfach. Da diese nicht installiert werden müssen, müssen Sie nur den Konfigurationswert html_theme festlegen. Um beispielsweise das classic-Theme zu aktivieren, fügen Sie Folgendes zu conf.py hinzu:

html_theme = "classic"

Sie können auch Theme-spezifische Optionen über den Konfigurationswert html_theme_options festlegen. Diese Optionen werden im Allgemeinen verwendet, um das Erscheinungsbild des Themes zu ändern. Um beispielsweise die Seitenleiste auf der rechten Seite und einen schwarzen Hintergrund für die Relationsleiste (die Leiste mit den Navigationslinks oben und unten auf der Seite) festzulegen, fügen Sie Folgendes zu conf.py hinzu:

html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

Wenn das Theme nicht mit Sphinx geliefert wird, kann es in zwei statischen Formen oder als Python-Paket vorliegen. Für die statischen Formen wird entweder ein Verzeichnis (das theme.toml und andere benötigte Dateien enthält) oder eine Zip-Datei mit demselben Inhalt unterstützt. Das Verzeichnis oder die Zip-Datei muss dort platziert werden, wo Sphinx sie finden kann. Dafür gibt es den Konfigurationswert html_theme_path. Dies kann eine Liste von Verzeichnissen sein, relativ zu dem Verzeichnis, das conf.py enthält und Theme-Verzeichnisse oder Zip-Dateien enthalten kann. Wenn Sie beispielsweise ein Theme in der Datei blue.zip haben, können Sie es direkt im Verzeichnis platzieren, das conf.py enthält, und diese Konfiguration verwenden:

html_theme = "blue"
html_theme_path = ["."]

Die dritte Form ist ein Python-Paket. Wenn ein Theme, das Sie verwenden möchten, als Python-Paket vertrieben wird, können Sie es nach der Installation verwenden.

# installing theme package
$ pip install sphinxjp.themes.dotted

Nach der Installation kann dies auf dieselbe Weise wie ein Theme, das auf Verzeichnissen oder Zip-Dateien basiert, verwendet werden.

html_theme = "dotted"

Weitere Informationen zum Design von Themes, einschließlich Informationen zur Erstellung eigener Themes, finden Sie unter Entwicklung von HTML-Themes.

Integrierte Themes

Theme-Übersicht

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

Sphinx wird mit einer Auswahl an Themes geliefert.

Beachten Sie, dass von diesen Themes nur die Alabaster- und Scrolls-Themes für mobile Geräte optimiert sind; die anderen Themes greifen auf horizontales Scrollen zurück, wenn der Bildschirm zu schmal ist.

Diese Themes sind:

basic

Dies ist ein grundlegend ungestaltetes Layout, das als Basis für die anderen Themes dient und auch als Basis für benutzerdefinierte Themes verwendet werden kann. Das HTML enthält alle wichtigen Elemente wie Seitenleiste und Relationsleiste. Es gibt folgende Optionen (die von den anderen Themes geerbt werden):

  • nosidebar (wahr oder falsch): Enthält die Seitenleiste nicht. Standardmäßig False.

  • sidebarwidth (int oder str): Breite der Seitenleiste in Pixeln. Dies kann eine Ganzzahl sein, die als Pixel interpretiert wird, oder eine gültige CSS-Dimensionszeichenfolge wie „70em“ oder „50 %“. Standardmäßig 230 Pixel.

  • body_min_width (int oder str): Minimale Breite des Dokumentenrumpfs. Dies kann eine Ganzzahl sein, die als Pixel interpretiert wird, oder eine gültige CSS-Dimensionszeichenfolge wie „70em“ oder „50 %“. Verwenden Sie 0, wenn Sie keine Breitenbegrenzung wünschen. Standardwerte können je nach Theme variieren (oft 450px).

  • body_max_width (int oder str): Maximale Breite des Dokumentenrumpfs. Dies kann eine Ganzzahl sein, die als Pixel interpretiert wird, oder eine gültige CSS-Dimensionszeichenfolge wie „70em“ oder „50 %“. Verwenden Sie „none“, wenn Sie keine Breitenbegrenzung wünschen. Standardwerte können je nach Theme variieren (oft 800px).

  • navigation_with_keys (wahr oder falsch): Ermöglicht die Navigation mit den folgenden Tastenkombinationen:

    • Pfeil links: vorherige Seite

    • Pfeil rechts: nächste Seite

    Standardmäßig False.

  • enable_search_shortcuts (wahr oder falsch): Ermöglicht das Springen zur Suchleiste mit / und das Entfernen der Suchhervorhebung mit Esc.

    Standardmäßig True.

  • globaltoc_collapse (wahr oder falsch): Nur Unterabschnitte des aktuellen Dokuments in globaltoc.html erweitern (siehe html_sidebars). Standardmäßig True.

    Hinzugefügt in Version 3.1.

  • globaltoc_includehidden (wahr oder falsch): Zeigt auch die Unterabschnitte in globaltoc.html (siehe html_sidebars) an, die mit dem Flag :hidden: der toctree-Direktive eingeschlossen wurden. Standardmäßig False.

    Hinzugefügt in Version 3.1.

  • globaltoc_maxdepth (int): Die maximale Tiefe des Toctree in globaltoc.html (siehe html_sidebars). Setzen Sie es auf -1, um eine unbegrenzte Tiefe zu ermöglichen. Standardmäßig die im Toctree-Directive ausgewählte maximale Tiefe.

    Hinzugefügt in Version 3.2.

alabaster

Alabaster-Theme ist ein modifiziertes „Kr“-Sphinx-Theme von @kennethreitz (insbesondere wie es in seinem Requests-Projekt verwendet wurde), das selbst ursprünglich auf dem Theme von @mitsuhiko basierte, das für Flask und verwandte Projekte verwendet wurde. Auf dessen Installationsseite finden Sie Informationen zur Konfiguration von html_sidebars für seine Verwendung.

classic

Dies ist das klassische Theme, das wie die Python 2-Dokumentation aussieht. Es kann über folgende Optionen angepasst werden:

  • rightsidebar (wahr oder falsch): Verschiebt die Seitenleiste nach rechts. Standardmäßig False.

  • stickysidebar (wahr oder falsch): Macht die Seitenleiste „fest“, sodass sie bei langem Inhalt nicht aus dem Sichtfeld scrollt. Dies funktioniert möglicherweise nicht gut mit allen Browsern. Standardmäßig False.

  • collapsiblesidebar (wahr oder falsch): Fügt ein *experimentelles* JavaScript-Snippet hinzu, das die Seitenleiste über eine Schaltfläche an ihrer Seite einklappbar macht. Standardmäßig False.

  • externalrefs (wahr oder falsch): Zeigt externe Links anders an als interne Links. Standardmäßig False.

Es gibt auch verschiedene Farb- und Schriftoptionen, die das Farbschema ändern können, ohne dass ein benutzerdefiniertes Stylesheet geschrieben werden muss.

  • footerbgcolor (CSS-Farbe): Hintergrundfarbe für die Fußzeile.

  • footertextcolor (CSS-Farbe): Textfarbe für die Fußzeile.

  • sidebarbgcolor (CSS-Farbe): Hintergrundfarbe für die Seitenleiste.

  • sidebarbtncolor (CSS-Farbe): Hintergrundfarbe für die Schaltfläche zum Einklappen der Seitenleiste (verwendet, wenn collapsiblesidebar True ist).

  • sidebartextcolor (CSS-Farbe): Textfarbe für die Seitenleiste.

  • sidebarlinkcolor (CSS-Farbe): Linkfarbe für die Seitenleiste.

  • relbarbgcolor (CSS-Farbe): Hintergrundfarbe für die Relationsleiste.

  • relbartextcolor (CSS-Farbe): Textfarbe für die Relationsleiste.

  • relbarlinkcolor (CSS-Farbe): Linkfarbe für die Relationsleiste.

  • bgcolor (CSS-Farbe): Hintergrundfarbe des Rumpfes.

  • textcolor (CSS-Farbe): Textfarbe des Rumpfes.

  • linkcolor (CSS-Farbe): Linkfarbe des Rumpfes.

  • visitedlinkcolor (CSS-Farbe): Farbe des Rumpfes für besuchte Links.

  • headbgcolor (CSS-Farbe): Hintergrundfarbe für Überschriften.

  • headtextcolor (CSS-Farbe): Textfarbe für Überschriften.

  • headlinkcolor (CSS-Farbe): Linkfarbe für Überschriften.

  • codebgcolor (CSS-Farbe): Hintergrundfarbe für Codeblöcke.

  • codetextcolor (CSS-Farbe): Standardtextfarbe für Codeblöcke, falls nicht anders durch den Hervorhebungsstil festgelegt.

  • bodyfont (CSS-Schriftartfamilie): Schriftart für normalen Text.

  • headfont (CSS-Schriftartfamilie): Schriftart für Überschriften.

sphinxdoc

Das ursprünglich von dieser Dokumentation verwendete Theme. Es verfügt über eine Seitenleiste auf der rechten Seite. Derzeit gibt es keine weiteren Optionen als nosidebar und sidebarwidth.

Hinweis

Die Sphinx-Dokumentation verwendet jetzt eine angepasste Version des sphinxdoc-Themes.

scrolls

Ein leichteres Theme, basierend auf der Jinja-Dokumentation. Folgende Farboptionen sind verfügbar:

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

Ein von Andi Albrecht erstelltes Theme. Folgende Optionen werden unterstützt:

  • bodyfont (CSS-Schriftartfamilie): Schriftart für normalen Text.

  • headerfont (CSS-Schriftartfamilie): Schriftart für Überschriften.

  • pagewidth (CSS-Länge): Breite des Seiteninhalts, Standard 70em.

  • documentwidth (CSS-Länge): Breite des Dokuments (ohne Seitenleiste), Standard 50em.

  • sidebarwidth (CSS-Länge): Breite der Seitenleiste, Standard 20em.

  • rightsidebar (wahr oder falsch): Verschiebt die Seitenleiste nach rechts. Standardmäßig True.

  • bgcolor (CSS-Farbe): Hintergrundfarbe.

  • headerbg (CSS-Wert für „background“): Hintergrund für den Kopfbereich, Standard ein gräulicher Verlauf.

  • footerbg (CSS-Wert für „background“): Hintergrund für den Fußbereich, Standard ein hellgrauer Verlauf.

  • linkcolor (CSS-Farbe): Linkfarbe des Rumpfes.

  • headercolor1, headercolor2 (CSS-Farben): Farben für <h1>- und <h2>-Überschriften.

  • headerlinkcolor (CSS-Farbe): Farbe für den Rückverweis-Link in Überschriften.

  • textalign (CSS-Wert für text-align): Textausrichtung für den Rumpf, Standard ist justify.

nature

Ein grünliches Theme. Derzeit gibt es keine weiteren Optionen als nosidebar und sidebarwidth.

pyramid

Ein Theme aus dem Pyramid-Webframework-Projekt, entworfen von Blaise Laflamme. Derzeit gibt es keine weiteren Optionen als nosidebar und sidebarwidth.

haiku

Ein Theme ohne Seitenleiste, inspiriert von der Haiku OS Benutzerhandbuch. Folgende Optionen werden unterstützt:

  • full_logo (wahr oder falsch, Standard False): Wenn wahr, zeigt der Kopf nur das html_logo an. Verwenden Sie dies für große Logos. Wenn falsch, wird das Logo (falls vorhanden) rechts schwebend angezeigt und der Dokumentationstitel in den Kopf gesetzt.

  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS-Farben): Farben für verschiedene Elemente des Rumpfes.

traditional

Ein Theme, das der alten Python-Dokumentation ähnelt. Derzeit gibt es keine weiteren Optionen als nosidebar und sidebarwidth.

epub

Ein Theme für den EPUB-Builder. Dieses Theme versucht, visuellen Platz zu sparen, der auf E-Book-Readern eine knappe Ressource ist. Folgende Optionen werden unterstützt:

  • relbar1 (wahr oder falsch, Standard True): Wenn wahr, wird der relbar1-Block in die EPUB-Ausgabe eingefügt, andernfalls wird er weggelassen.

  • footer (wahr oder falsch, Standard True): Wenn wahr, wird der footer-Block in die EPUB-Ausgabe eingefügt, andernfalls wird er weggelassen.

bizstyle

Ein einfaches bläuliches Theme. Folgende Optionen werden zusätzlich zu nosidebar und sidebarwidth unterstützt:

  • rightsidebar (wahr oder falsch): Verschiebt die Seitenleiste nach rechts. Standardmäßig False.

Hinzugefügt in Version 1.3: „alabaster“, „sphinx_rtd_theme“ und „bizstyle“-Theme.

Geändert in Version 1.3: Das Theme „default“ wurde in „classic“ umbenannt. „default“ ist weiterhin verfügbar, wird jedoch eine Benachrichtigung ausgeben, dass es ein Alias für das neue Theme „alabaster“ ist.

Drittanbieter-Themes

Es gibt viele von Drittanbietern erstellte Themes für Sphinx. Einige davon sind für den allgemeinen Gebrauch bestimmt, während andere spezifisch für ein einzelnes Projekt sind.

sphinx-themes.org ist eine Galerie, die verschiedene Themes für Sphinx präsentiert, mit Demo-Dokumentation, die unter jedem Theme gerendert wird. Themes können auch auf PyPI (unter Verwendung des Klassifikators Framework :: Sphinx :: Theme), GitHub und GitLab gefunden werden.