Templating¶

Was ist Templating?¶

Templating ist eine Methode zur Erzeugung von HTML-Seiten durch die Kombination von statischen Vorlagen mit variablen Daten. Die Vorlagendateien enthalten die statischen Teile des gewünschten HTML-Outputs und enthalten eine spezielle Syntax, die beschreibt, wie variable Inhalte eingefügt werden. Dies kann beispielsweise dazu verwendet werden, das aktuelle Datum in der Fußzeile jeder Seite einzufügen oder den Hauptinhalt des Dokuments mit einem Gerüst aus HTML für Layout und Formatierung zu umschließen. Dazu sind nur Kenntnisse von HTML und der Templating-Syntax erforderlich. Kenntnisse von Python können hilfreich, sind aber nicht zwingend erforderlich.

Templating verwendet einen Vererbungsmechanismus, der es Kind-Vorlagendateien (z. B. in einem Theme) ermöglicht, so viel (oder so wenig) von ihren „Eltern“ zu überschreiben, wie gewünscht. Ebenso können Autoren Inhalte ihre eigenen lokalen Vorlagen verwenden, um so viel (oder so wenig) von den Theme-Vorlagen zu überschreiben, wie gewünscht.

Das Ergebnis ist, dass die Sphinx-Kernfunktionalität ohne Änderung eine grundlegende HTML-Erzeugung bereitstellt, unabhängig von der Struktur und dem Erscheinungsbild des endgültigen Outputs, während gleichzeitig eine große Flexibilität für Theme- und Content-Autoren gewährt wird.

Sphinx Templating¶

Sphinx verwendet die Jinja Templating-Engine für seine HTML-Vorlagen. Jinja ist eine textbasierte Engine, inspiriert von Django-Vorlagen, sodass jeder, der Django verwendet hat, damit bereits vertraut ist. Sie verfügt auch über eine ausgezeichnete Dokumentation für diejenigen, die sich damit vertraut machen müssen.

Muss ich Sphinx-Vorlagen verwenden, um HTML zu erzeugen?¶

Nein. Sie haben mehrere andere Optionen

Sie können eine TemplateBridge-Unterklasse schreiben, die Ihre Vorlagen-Engine Ihrer Wahl aufruft, und den Konfigurationswert template_bridge entsprechend einstellen.
Sie können einen benutzerdefinierten Builder schreiben, der von StandaloneHTMLBuilder abgeleitet ist und Ihre Vorlagen-Engine Ihrer Wahl aufruft.
Sie können den PickleHTMLBuilder verwenden, der Pickle-Dateien mit den Seiteninhalten erzeugt, und diese mit einem benutzerdefinierten Tool nachbearbeiten oder in Ihrer Webanwendung verwenden.

Jinja/Sphinx Templating Primer¶

Die Standard-Templating-Sprache in Sphinx ist Jinja. Sie ist von Django/Smarty inspiriert und leicht verständlich. Das wichtigste Konzept in Jinja ist die Vorlagenvererbung, was bedeutet, dass Sie nur bestimmte Blöcke innerhalb einer Vorlage überschreiben können, um sie anzupassen und gleichzeitig die Änderungen auf ein Minimum zu beschränken.

Um die Ausgabe Ihrer Dokumentation anzupassen, können Sie alle Vorlagen (sowohl die Layout-Vorlagen als auch die Kind-Vorlagen) überschreiben, indem Sie Dateien mit demselben Namen wie der ursprüngliche Dateiname in das Vorlagenverzeichnis der von Sphinx-Quickstart erstellten Struktur einfügen.

Sphinx sucht zuerst in den Ordnern von templates_path nach Vorlagen und greift dann auf die Vorlagen des ausgewählten Themes zurück, wenn es die gesuchte Vorlage dort nicht findet.

Eine Vorlage enthält **Variablen**, die beim Auswerten der Vorlage durch Werte ersetzt werden, **Tags**, die die Logik der Vorlage steuern, und **Blöcke**, die für die Vorlagenvererbung verwendet werden.

Das *Standard*-Theme von Sphinx stellt Basistemplates mit einigen Blöcken bereit, die es mit Daten füllt. Diese befinden sich im Unterverzeichnis themes/basic des Sphinx-Installationsverzeichnisses und werden von allen integrierten Sphinx-Themes verwendet. Vorlagen mit demselben Namen im templates_path überschreiben Vorlagen, die vom ausgewählten Theme bereitgestellt werden.

Um beispielsweise einen neuen Link zum Vorlagenbereich mit verwandten Links hinzuzufügen, müssen Sie nur eine neue Vorlage namens layout.html mit folgendem Inhalt erstellen

{% extends "!layout.html" %}
{% block rootrellink %}
    <li><a href="https://project.invalid/">Project Homepage</a> &raquo;</li>
    {{ super() }}
{% endblock %}

Durch Voranstellen eines Ausrufezeichens vor den Namen der überschriebenen Vorlage lädt Sphinx die Layout-Vorlage aus dem zugrunde liegenden HTML-Theme.

Wichtig

Wenn Sie einen Block überschreiben, rufen Sie irgendwo {{ super() }} auf, um den ursprünglichen Inhalt des Blocks in der erweiterten Vorlage darzustellen – es sei denn, Sie möchten, dass dieser Inhalt nicht angezeigt wird.

Arbeiten mit den integrierten Vorlagen¶

Das integrierte **Basic**-Theme stellt die Vorlagen bereit, auf denen alle integrierten Sphinx-Themes basieren. Es hat die folgenden Elemente, die Sie überschreiben oder verwenden können

Blöcke¶

Die folgenden Blöcke existieren in der Vorlage layout.html

doctype

Der Doctype des Ausgabeformats. Standardmäßig ist dies XHTML 1.0 Transitional, da dies dem am nächsten kommt, was Sphinx und Docutils erzeugen, und es ist eine gute Idee, ihn nicht zu ändern, es sei denn, Sie möchten zu HTML 5 oder einem anderen, aber kompatiblen XHTML-Doctype wechseln.

linktags

Dieser Block fügt einige <link>-Tags in den Kopfbereich der Vorlage ein.

extrahead

Dieser Block ist standardmäßig leer und kann verwendet werden, um zusätzliche Inhalte in den <head>-Tag der generierten HTML-Datei einzufügen. Dies ist der richtige Ort, um Verweise auf JavaScript oder zusätzliche CSS-Dateien hinzuzufügen.

relbar1, relbar2

Dieser Block enthält die *Relationsleiste*, die Liste der verwandten Links (die übergeordneten Dokumente links und die Links zum Index, zu Modulen usw. rechts). relbar1 erscheint vor dem Dokument, relbar2 nach dem Dokument. Standardmäßig sind beide Blöcke gefüllt; um die Relbar nur vor dem Dokument anzuzeigen, würden Sie relbar2 wie folgt überschreiben

{% block relbar2 %}{% endblock %}

rootrellink, relbaritems

Innerhalb der Relationsleiste gibt es drei Abschnitte: Den rootrellink, die Links aus der Dokumentation und die benutzerdefinierten relbaritems. Der rootrellink ist ein Block, der standardmäßig ein Listenelement enthält, das auf das Stammverzeichnis verweist, während relbaritems ein leerer Block ist. Wenn Sie diese überschreiben, um zusätzliche Links zur Leiste hinzuzufügen, stellen Sie sicher, dass es sich um Listenelemente handelt und mit dem reldelim1 enden.

document

Der Inhalt des Dokuments selbst. Er enthält den Block „body“, in den die einzelnen Inhalte von Untervorlagen wie page.html eingefügt werden.

Hinweis

Damit die integrierte JavaScript-Suche eine Seiten-Vorschau auf der Ergebnisseite anzeigen kann, sollte der Dokument- oder Inhaltskörper in ein HTML-Element mit dem Attribut role="main" eingeschlossen werden. Zum Beispiel

<div role="main">
  {% block document %}{% endblock %}
</div>

sidebar1, sidebar2

Eine mögliche Position für eine Seitenleiste. sidebar1 erscheint vor dem Dokument und ist standardmäßig leer, sidebar2 nach dem Dokument und enthält die Standard-Seitenleiste. Wenn Sie die Position der Seitenleiste tauschen möchten, überschreiben Sie dies und rufen Sie die Hilfsfunktion sidebar auf

{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}

(Die sidebar2-Position für die Seitenleiste wird beispielsweise vom sphinxdoc.css-Stylesheet benötigt.)

sidebarlogo

Die Logo-Position innerhalb der Seitenleiste. Überschreiben Sie dies, wenn Sie Inhalte am oberen Rand der Seitenleiste platzieren möchten.

footer

Der Block für das Fußzeilen-DIV. Wenn Sie eine benutzerdefinierte Fußzeile oder Markup davor oder danach wünschen, überschreiben Sie diesen.

Die folgenden vier Blöcke werden *nur* für Seiten verwendet, denen keine Liste benutzerdefinierter Seitenleisten in der Konfigurationsvariable html_sidebars zugewiesen ist. Ihre Verwendung ist zugunsten separater Seitenleisten-Vorlagen veraltet, die über html_sidebars eingebunden werden können.

sidebartoc: Das Inhaltsverzeichnis innerhalb der Seitenleiste.

Veraltet seit Version 1.0.
sidebarrel: Die Relationslinks (vorheriges, nächstes Dokument) innerhalb der Seitenleiste.

Veraltet seit Version 1.0.
sidebarsourcelink: Der Link „Quellcode anzeigen“ in der Seitenleiste (normalerweise nur angezeigt, wenn dies durch html_show_sourcelink aktiviert ist).

Veraltet seit Version 1.0.
sidebarsearch: Das Suchfeld innerhalb der Seitenleiste. Überschreiben Sie dies, wenn Sie Inhalte am unteren Rand der Seitenleiste platzieren möchten.

Veraltet seit Version 1.0.

Konfigurationsvariablen¶

Innerhalb von Vorlagen können Sie mit dem Tag {% set %} einige Variablen einstellen, die von der Layout-Vorlage verwendet werden

reldelim1¶: Der Trenner für die Elemente auf der linken Seite der Relationsleiste. Dieser ist standardmäßig ' »'. Jedes Element in der Relationsleiste endet mit dem Wert dieser Variablen.

reldelim2¶: Der Trenner für die Elemente auf der rechten Seite der Relationsleiste. Dieser ist standardmäßig ' |'. Jedes Element außer dem letzten in der Relationsleiste endet mit dem Wert dieser Variablen.

Das Überschreiben funktioniert so

{% extends "!layout.html" %}
{% set reldelim1 = ' &gt;' %}

script_files¶

Fügen Sie hier zusätzliche Skriptdateien hinzu, wie folgt

{% set script_files = script_files + ["_static/myscript.js"] %}

Veraltet seit Version 1.8.0: Verwenden Sie stattdessen .Sphinx.add_js_file().

Hilfsfunktionen¶

Sphinx stellt verschiedene Jinja-Funktionen als Helfer in der Vorlage bereit. Sie können diese verwenden, um Links oder mehrfach verwendete Elemente zu generieren.

pathto(document)¶: Gibt den Pfad zu einem Sphinx-Dokument als URL zurück. Verwenden Sie dies, um auf erstellte Dokumente zu verweisen.

pathto(file, 1): Gibt den Pfad zu einer *Datei* zurück, die ein Dateiname relativ zum Stammverzeichnis des generierten Outputs ist. Verwenden Sie dies, um auf statische Dateien zu verweisen.

hasdoc(document)¶: Überprüft, ob ein Dokument mit dem Namen *document* existiert.

sidebar()¶: Gibt die gerenderte Seitenleiste zurück.

relbar()¶: Gibt die gerenderte Relationsleiste zurück.

warning(message)¶: Gibt eine Warnmeldung aus.

Globale Variablen¶

Diese globalen Variablen sind in jeder Vorlage verfügbar und sicher zu verwenden. Es gibt mehr, aber die meisten davon sind Implementierungsdetails und könnten sich in Zukunft ändern.

builder¶: Der Name des Builders (z. B. html oder htmlhelp).

copyright¶: Der Wert von copyright.

docstitle¶: Der Titel der Dokumentation (der Wert von html_title), außer wenn der „Single-File“-Builder verwendet wird, dann ist er auf None gesetzt.

embedded¶: True, wenn das erstellte HTML dazu bestimmt ist, in eine Anwendung eingebettet zu werden, die die Navigation handhabt, nicht in einen Webbrowser, wie z. B. für HTML Help- oder Qt Help-Formate. In diesem Fall wird die Seitenleiste nicht eingeschlossen.

favicon_url¶: Der relative Pfad zum HTML-Favicon-Bild vom aktuellen Dokument, oder die URL zum Favicon, oder ''.

Hinzugefügt in Version 4.0.

file_suffix¶: Der Wert des out_suffix-Attributs des Builders, d. h. die Dateinamenerweiterung, die die Ausgabedateien erhalten. Für einen Standard-HTML-Builder ist dies normalerweise .html.

has_source¶: True, wenn die reStructuredText-Dokumentquellen kopiert werden (wenn html_copy_source True ist).

language¶: Der Wert von language.

last_updated¶: Das Erstellungsdatum.

logo_url¶: Der relative Pfad zum HTML-Logo-Bild vom aktuellen Dokument, oder die URL zum Logo, oder ''.

Hinzugefügt in Version 4.0.

master_doc¶
root_doc¶: Der Wert von master_doc oder root_doc (Aliase) zur Verwendung mit pathto().

Hinzugefügt in Version 4.0: Die Template-Variable root_doc.

pagename¶: Der „Seitenname“ der aktuellen Datei, d. h. entweder der Dokumentenname, wenn die Datei aus einer reStructuredText-Quelle generiert wird, oder der entsprechende hierarchische Name relativ zum Ausgabeordner ([directory/]filename_without_extension).

project¶: Der Wert von project.

release¶: Der Wert von release.

rellinks¶: Eine Liste von Links, die auf der linken Seite der Relationsleiste neben „next“ und „prev“ platziert werden. Dies enthält normalerweise Links zum allgemeinen Index und anderen Indizes, wie z. B. dem Python-Modulindex. Wenn Sie etwas selbst hinzufügen, muss es ein Tupel sein (pagename, link title, accesskey, link text).

shorttitle¶: Der Wert von html_short_title.

show_source¶: True, wenn html_show_sourcelink True ist.

sphinx_version¶: Die Version von Sphinx, die zum Erstellen verwendet wurde, als Zeichenkette, z. B. „3.5.1“.

sphinx_version_tuple¶: Die Version von Sphinx, die zum Erstellen verwendet wurde, als Tupel aus fünf Elementen. Für Sphinx-Version 3.5.1 beta 3 wäre dies (3, 5, 1, 'beta', 3). Das vierte Element kann eines der folgenden sein: alpha, beta, rc, final. final hat immer 0 als letztes Element.

Hinzugefügt in Version 4.2.

docutils_version_info¶: Die Version von Docutils, die zum Erstellen verwendet wurde, als Tupel aus fünf Elementen. Für Docutils-Version 0.16.1 beta 2 wäre dies (0, 16, 1, 'beta', 2). Das vierte Element kann eines der folgenden sein: alpha, beta, candidate, final. final hat immer 0 als letztes Element.

Hinzugefügt in Version 5.0.2.

styles¶: Eine Liste der Namen der Haupt-Stylesheets, wie sie vom Theme oder von html_style angegeben werden.

Hinzugefügt in Version 5.1.

title¶: Der Titel des aktuellen Dokuments, wie er im <title>-Tag verwendet wird.

use_opensearch¶: Der Wert von html_use_opensearch.

version¶: Der Wert von version.

Zusätzlich zu diesen Werten sind auch alle **Theme-Optionen** verfügbar (präfixiert mit theme_) sowie die vom Benutzer in html_context angegebenen Werte.

In Dokumenten, die aus Quellcodedateien erstellt werden (im Gegensatz zu automatisch generierten Dateien wie dem Modulindex oder Dokumenten, die bereits im HTML-Format vorliegen), sind auch diese Variablen verfügbar

body¶: Eine Zeichenkette, die den Inhalt der Seite in HTML-Form enthält, wie vom HTML-Builder erzeugt, bevor das Theme angewendet wird.

display_toc¶: Ein boolescher Wert, der True ist, wenn das TOC mehr als einen Eintrag enthält.

meta¶: Dokumentmetadaten (ein Wörterbuch), siehe Dateibezogene Metadaten.

metatags¶: Eine Zeichenkette, die die HTML-meta-Tags der Seite enthält.

next¶

Das nächste Dokument für die Navigation. Diese Variable ist entweder falsch oder hat zwei Attribute: link und title. Der Titel enthält HTML-Markup. Zum Beispiel können Sie zur Erstellung eines Links zur nächsten Seite dieses Snippet verwenden

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}

page_source_suffix¶: Die Erweiterung der Datei, die gerendert wurde. Da wir eine Liste von source_suffix unterstützen, können Sie so richtig auf die ursprüngliche Quelldatei verlinken.

parents¶: Eine Liste von übergeordneten Dokumenten für die Navigation, strukturiert wie das next-Element.

prev¶: Wie next, aber für die vorherige Seite.

sourcename¶: Der Name der kopierten Quelldatei für das aktuelle Dokument. Dies ist nur dann nicht leer, wenn der Wert von html_copy_source True ist. Dies hat einen leeren Wert, wenn automatisch generierte Dateien erstellt werden.

toc¶: Das lokale Inhaltsverzeichnis für die aktuelle Seite, gerendert als HTML-Aufzählungslisten.

toctree¶

Eine aufrufbare Funktion, die den globalen TOC-Baum liefert, der die aktuelle Seite enthält, gerendert als HTML-Aufzählungslisten. Optionale Schlüsselwortargumente

collapse: Wenn True, werden alle TOC-Einträge, die keine Vorfahren der aktuellen Seite sind, eingeklappt. Standardmäßig True.
maxdepth: Die maximale Tiefe des Baumes. Setzen Sie es auf -1, um unbegrenzte Tiefe zu ermöglichen. Standardmäßig ist die maximale Tiefe, die in der toctree-Direktive ausgewählt wurde.
titles_only: Wenn True, werden nur Titel der obersten Ebene des Dokuments in den Baum aufgenommen. Standardmäßig False.
includehidden: Wenn True, enthält der TOC-Baum auch versteckte Einträge. Standardmäßig False.