Direktiven¶

Wie bereits erwähnt, ist eine Direktive ein generischer Block expliziter Auszeichnung. Während Docutils eine Reihe von Direktiven bereitstellt, bietet Sphinx viele mehr und nutzt Direktiven als einen der primären Erweiterungsmechanismen. (Wie bereits besprochen)

Siehe Domänen für Rollen, die von Domänen hinzugefügt werden.

Siehe auch

Für eine Übersicht über die von Docutils bereitgestellten Direktiven siehe das reStructuredText-Handbuch.

Inhaltsverzeichnis¶

Da reStructuredText keine Einrichtungen zur Verknüpfung mehrerer Dokumente oder zur Aufteilung von Dokumenten in mehrere Ausgabedateien bietet, verwendet Sphinx eine benutzerdefinierte Direktive, um Beziehungen zwischen den einzelnen Dateien, aus denen die Dokumentation besteht, sowie Inhaltsverzeichnisse hinzuzufügen. Die toctree-Direktive ist das zentrale Element.

Hinweis

Das einfache „Einfügen“ einer Datei in eine andere kann mit der include-Direktive erfolgen.

Hinweis

Um ein Inhaltsverzeichnis für das aktuelle Dokument (RST-Datei) zu erstellen, verwenden Sie die Standard-reStructuredText- contents-Direktive.

.. toctree::¶

Diese Direktive fügt an der aktuellen Stelle einen „Inhaltsbaum“ ein, der die einzelnen Inhaltsverzeichnisse (einschließlich „Unter-Inhaltsbäume“) der im Direktivenkörper angegebenen Dokumente verwendet. Relative Dokumentennamen (die nicht mit einem Schrägstrich beginnen) beziehen sich auf das Dokument, in dem die Direktive vorkommt, absolute Namen sind relativ zum Quellverzeichnis. Eine numerische Option maxdepth kann angegeben werden, um die Tiefe des Baumes anzugeben; standardmäßig werden alle Ebenen einbezogen. [1]

Die Darstellung des „Inhaltsbaumes“ wird in jedem Ausgabeformat geändert. Die Builder, die mehrere Dateien ausgeben (z.B. HTML), behandeln ihn als eine Sammlung von Hyperlinks. Auf der anderen Seite ersetzen die Builder, die eine einzelne Datei ausgeben (z.B. LaTeX, Manpage usw.), ihn durch den Inhalt der Dokumente im Inhaltsbaum.

Betrachten Sie dieses Beispiel (aus dem Bibliotheksreferenzindex der Python-Dokumente)

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

Dies bewirkt zwei Dinge

Die Inhaltsverzeichnisse aller dieser Dokumente werden eingefügt, mit einer maximalen Tiefe von zwei, was einer verschachtelten Überschrift entspricht. toctree-Direktiven in diesen Dokumenten werden ebenfalls berücksichtigt.
Sphinx kennt die relative Reihenfolge der Dokumente intro, strings und so weiter und weiß, dass sie Kinder des angezeigten Dokuments, des Bibliotheksindexes, sind. Aus dieser Information generiert es Links zu „nächstes Kapitel“, „vorheriges Kapitel“ und „übergeordnetes Kapitel“.

Einträge

Dokumenttitel im toctree werden automatisch aus dem Titel des referenzierten Dokuments gelesen. Wenn Sie dies nicht wünschen, können Sie einen expliziten Titel und ein Ziel angeben, indem Sie eine ähnliche Syntax wie bei reStructuredText-Hyperlinks (und Sphinx' Cross-Referencing-Syntax) verwenden. Dies sieht so aus:

.. toctree::

   intro
   All about strings <strings>
   datatypes

Die zweite Zeile oben verknüpft mit dem Dokument strings, verwendet aber den Titel „Alles über Strings“ anstelle des Titels des Dokuments strings.

Sie können auch externe Links hinzufügen, indem Sie eine HTTP-URL anstelle eines Dokumentnamens angeben.

Der spezielle Eintragsname self steht für das Dokument, das die toctree-Direktive enthält. Dies ist nützlich, wenn Sie eine „Sitemap“ aus dem toctree generieren möchten.

Am Ende müssen alle Dokumente im Quellverzeichnis (oder Unterverzeichnissen) in einer toctree-Direktive vorkommen; Sphinx gibt eine Warnung aus, wenn es eine Datei findet, die nicht enthalten ist, da diese Datei über die normale Navigation nicht erreichbar ist.

Verwenden Sie exclude_patterns, um Dokumente oder Verzeichnisse vollständig vom Erstellen auszuschließen. Verwenden Sie die „orphan“-Metadaten, damit ein Dokument erstellt wird, aber Sphinx benachrichtigt wird, dass es nicht über ein toctree erreichbar ist.

Das „Root-Dokument“ (ausgewählt durch root_doc) ist die „Wurzel“ der Inhaltsbaumhierarchie. Es kann als Hauptseite der Dokumentation oder als „vollständiges Inhaltsverzeichnis“ verwendet werden, wenn Sie keine :maxdepth:-Option angeben.

Geändert in Version 0.6: Unterstützung für externe Links und „self“-Referenzen hinzugefügt.

Optionen

:class: Klassennamen (eine Liste von Klassennamen, durch Leerzeichen getrennt)¶

Weisen Sie Klassenattribute zu. Dies ist eine allgemeine Option. Zum Beispiel

.. toctree::
   :class: custom-toc

Hinzugefügt in Version 7.4.

:name: Label (Text)¶

Ein impliziter Zielname, auf den mit der ref-Rolle verwiesen werden kann. Dies ist eine allgemeine Option. Zum Beispiel

.. toctree::
   :name: mastertoc

   foo

Hinzugefügt in Version 1.3.

:caption: (Text)¶

Fügt eine Beschriftung zum toctree hinzu. Zum Beispiel

.. toctree::
   :caption: Table of Contents

    foo

Hinzugefügt in Version 1.3.

:numbered:¶

:numbered: Tiefe

Wenn Sie auch in der HTML-Ausgabe Abschnittsnummern wünschen, fügen Sie die Option :numbered: dem *obersten* toctree hinzu. Zum Beispiel

.. toctree::
   :numbered:

   foo
   bar

Die Nummerierung der Abschnitte beginnt dann mit der Überschrift von foo. Unter-Toctrees werden automatisch nummeriert (geben Sie die numbered-Flagge nicht an diese weiter).

Eine Nummerierung bis zu einer bestimmten Tiefe ist ebenfalls möglich, indem die Tiefe als numerisches Argument für numbered angegeben wird.

Hinzugefügt in Version 0.6.

Geändert in Version 1.1: Das numerische Argument *Tiefe* wurde hinzugefügt.

:titlesonly:¶

Listet nur Dokumenttitel auf, keine anderen Überschriften desselben Levels. Zum Beispiel

.. toctree::
   :titlesonly:

   foo
   bar

Hinzugefügt in Version 1.0.

:glob:¶

Parse glob-Wildcards in Toctree-Einträgen. Alle Einträge werden mit der Liste der verfügbaren Dokumente abgeglichen, und Übereinstimmungen werden alphabetisch in die Liste eingefügt. Zum Beispiel

.. toctree::
   :glob:

   intro*
   recipe/*
   *

Dies schließt zuerst alle Dokumente ein, deren Namen mit intro beginnen, dann alle Dokumente im Verzeichnis recipe, dann alle verbleibenden Dokumente (außer dem, das die Direktive enthält, natürlich). [2]

Hinzugefügt in Version 0.3.

:reversed:¶: Kehrt die Reihenfolge der Einträge in der Liste um. Dies ist besonders nützlich bei der Verwendung der Option :glob:.

Hinzugefügt in Version 1.5.

:hidden:¶

Ein versteckter Toctree definiert nur die Dokumentenhierarchie. Er fügt an der Stelle der Direktive keine Links in das Dokument ein.

Dies ist sinnvoll, wenn Sie andere Navigationsmöglichkeiten haben, z.B. über manuelle Links, die Navigation in der HTML-Seitenleiste oder wenn Sie die Option :includehidden: auf dem obersten Toctree verwenden.

Hinzugefügt in Version 0.6.

:includehidden:¶: Wenn Sie ein globales Inhaltsverzeichnis wünschen, das die vollständige Dokumentenstruktur zeigt, können Sie die Option :includehidden: zur *obersten* toctree-Direktive hinzufügen. Alle anderen Toctrees auf Kindseiten können dann mit der Option :hidden: unsichtbar gemacht werden. Der oberste Toctree mit :includehidden: wird dann deren Einträge aufnehmen.

Hinzugefügt in Version 1.2.

Spezielle Namen¶

Sphinx reserviert einige Dokumentennamen für den eigenen Gebrauch; Sie sollten nicht versuchen, Dokumente mit diesen Namen zu erstellen – dies wird zu Problemen führen.

Die speziellen Dokumentennamen (und die dafür generierten Seiten) sind

genindex

Diese wird für den allgemeinen Index verwendet, der mit Einträgen aus index-Direktiven und allen Index-generierenden Objektbeschreibungen gefüllt wird. Sehen Sie zum Beispiel Sphinx' Index.
modindex

Diese wird für den Python-Modulindex verwendet, der einen Eintrag pro py:module-Direktive enthält. Sehen Sie zum Beispiel Sphinx' Python-Modulindex.
search

Diese wird für die Suchseite verwendet, die ein Formular enthält, das den generierten JSON-Suchindex und JavaScript verwendet, um die generierten Dokumente auf Volltextsuche nach Suchwörtern zu durchsuchen; sie funktioniert auf jedem gängigen Browser. Sehen Sie zum Beispiel Sphinx' Suchseite.
Jeder Name, der mit _ beginnt

Obwohl derzeit nur wenige solcher Namen von Sphinx verwendet werden, sollten Sie keine Dokumente oder dokumentenenthaltenden Verzeichnisse mit solchen Namen erstellen. (Die Verwendung von _ als Präfix für ein benutzerdefiniertes Vorlagenverzeichnis ist in Ordnung.)

Warnung

Seien Sie vorsichtig mit ungewöhnlichen Zeichen in Dateinamen. Einige Formate können diese Zeichen unerwartet interpretieren

Verwenden Sie nicht den Doppelpunkt : für HTML-basierte Formate. Links zu anderen Teilen funktionieren möglicherweise nicht.
Verwenden Sie nicht das Pluszeichen + für das ePub-Format. Einige Ressourcen werden möglicherweise nicht gefunden.

Absatz-Markup¶

Diese Direktiven erstellen kurze Absätze und können sowohl innerhalb von Informationseinheiten als auch in normalem Text verwendet werden.

Anzeigen, Meldungen und Warnungen¶

Die Admonition-Direktiven erstellen „Admonition“-Elemente, ein standardisiertes System zur Kommunikation verschiedener Arten von Informationen, von einem hilfreichen tip bis hin zu Angelegenheiten von größter danger. Diese Direktiven können überall dort verwendet werden, wo ein gewöhnliches Bodenelement verwendet werden kann, und können beliebige Bodenelemente enthalten. Es gibt neun spezifische benannte Admonitionen und die generische admonition-Direktive.

.. attention::¶

Informationen, die die Aufmerksamkeit des Lesers erfordern. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Aufmerksamkeit

Bitte, darf ich Ihre Aufmerksamkeit erbitten.

.. caution::¶

Informationen, bei denen der Leser Vorsicht walten lassen sollte. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Vorsicht

Üben Sie gebührende Vorsicht.

.. danger::¶

Informationen, die zu unmittelbarer und gegenwärtiger Gefahr führen können, wenn sie nicht beachtet werden. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Gefahr

Niemand möge glauben, der Gefahr zu entkommen, denn bald oder spät wird die Liebe ihren eigenen Rächer finden.

.. error::¶

Informationen, die sich auf Fehlermodi einer gewissen Art beziehen. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Fehler

FEHLER 418: Ich bin eine Teekanne.

.. hint::¶

Informationen, die für den Leser hilfreich sind. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Hinweis

Schauen Sie unter dem Blumentopf nach.

.. important::¶

Informationen, die von größter Bedeutung sind und die der Leser nicht ignorieren darf. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Wichtig

Dies ist eine Aussage von größter Bedeutung.

.. note::¶

Ein besonders wichtiger Hinweis, den der Leser kennen sollte. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Hinweis

Diese Funktion ist nicht geeignet, um Dosen mit Wurst zu versenden.

.. tip::¶

Ein nützlicher Tipp für den Leser. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Tipp

Denken Sie an Ihre Sonnencreme!

.. warning::¶

Ein wichtiger Hinweis, dessen sich der Leser sehr bewusst sein sollte. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Warnung

Hüten Sie sich vor dem Hund.

.. admonition:: Titel¶

Eine generische Admonition mit einem optionalen Titel. Der Inhalt der Direktive sollte in vollständigen Sätzen geschrieben sein und alle relevanten Satzzeichen enthalten.

Beispiel

Das ist ein Titel

Das ist der Inhalt der Admonition.

.. seealso::¶

Viele Abschnitte enthalten eine Liste von Verweisen auf Moduldokumentationen oder externe Dokumente. Diese Listen werden mit der seealso-Direktive erstellt.

Die seealso-Direktive wird typischerweise in einem Abschnitt direkt vor Unterabschnitten platziert. Der Inhalt der seealso-Direktive sollte entweder eine einzelne Zeile oder eine reStructuredText- Definitionsliste sein.

Beispiel

.. seealso::

   Python's :py:mod:`zipfile` module
      Documentation of Python's standard :py:mod:`zipfile` module.

   `GNU tar manual, Basic Tar Format <https://example.org>`_
      Documentation for tar archive files, including GNU tar extensions.

Siehe auch

Das zipfile-Modul von Python: Dokumentation des zipfile-Standardmoduls von Python.
GNU tar-Handbuch, Basic Tar Format: Dokumentation für tar-Archive, einschließlich GNU tar-Erweiterungen.

Kollabierbarer Text

Hinzugefügt in Version 8.2.

Jede Admonition-Direktive unterstützt eine Option :collapsible:, um den Inhalt der Admonition kollabierbar zu machen (wo vom Ausgabeformat unterstützt). Dies kann für Inhalte nützlich sein, die nicht immer relevant sind. Standardmäßig sind kollabierbare Admonitionen zunächst geöffnet, dies kann jedoch mit den Argumenten open und closed der Option :collapsible: gesteuert werden, die den Standardzustand ändern. In Ausgabeformaten, die keinen kollabierbaren Inhalt unterstützen, wird der Text immer angezeigt. Zum Beispiel

.. note::
   :collapsible:

   This note is collapsible, and initially open by default.

.. admonition:: Example
   :collapsible: open

   This example is collapsible, and initially open.

.. hint::
   :collapsible: closed

   This hint is collapsible, but initially closed.

Hinweis

Diese Notiz ist kollabierbar und standardmäßig zunächst geöffnet.

Beispiel

Dieses Beispiel ist kollabierbar und standardmäßig geöffnet.

Hinweis

Dieser Hinweis ist kollabierbar, aber standardmäßig geschlossen.

Beschreiben von Änderungen zwischen Versionen¶

.. version-added:: Version [kurze Erklärung]¶

.. versionadded:: Version [kurze Erklärung]¶

Diese Direktive dokumentiert die Version des Projekts, die das beschriebene Feature hinzugefügt hat. Wenn dies für ein gesamtes Modul oder eine Komponente gilt, sollte sie am Anfang des relevanten Abschnitts vor jeglichem Text platziert werden.

Das erste Argument muss angegeben werden und ist die betreffende Version; Sie können ein zweites Argument hinzufügen, das eine *kurze* Erklärung der Änderung enthält.

Aufmerksamkeit

Zwischen dem Direktivenkopf und der Erklärung darf keine Leerzeile stehen; dies dient dazu, diese Blöcke im Markup visuell fortlaufend zu gestalten.

Geändert in Version 9.0: Die Direktive versionadded wurde in version-added umbenannt. Der vorherige Name bleibt als Alias erhalten.

Beispiel

.. version-added:: 2.5
   The *spam* parameter.

Hinzugefügt in Version 2.5: Der Parameter *spam*.

.. version-changed:: Version [kurze Erklärung]¶

.. versionchanged:: Version [kurze Erklärung]¶

Ähnlich wie version-added, beschreibt aber, wann und was sich an dem genannten Feature auf irgendeine Weise geändert hat (neue Parameter, geänderte Nebeneffekte usw.).

Geändert in Version 9.0: Die Direktive versionchanged wurde in version-changed umbenannt. Der vorherige Name bleibt als Alias erhalten.

Beispiel

.. version-changed:: 2.8
   The *spam* parameter is now of type *boson*.

Geändert in Version 2.8: Der Parameter *spam* hat nun den Typ *boson*.

.. version-deprecated:: Version [kurze Erklärung]¶

.. deprecated:: Version [kurze Erklärung]¶

Ähnlich wie version-added, beschreibt aber, wann das Feature als veraltet markiert wurde. Eine *kurze* Erklärung kann ebenfalls gegeben werden, um dem Leser beispielsweise mitzuteilen, was stattdessen verwendet werden soll.

Geändert in Version 9.0: Die Direktive deprecated wurde in version-deprecated umbenannt. Der vorherige Name bleibt als Alias erhalten.

Beispiel

.. version-deprecated:: 3.1
   Use :py:func:`spam` instead.

Veraltet seit Version 3.1: Verwenden Sie stattdessen spam().

.. version-removed:: Version [kurze Erklärung]¶

.. versionremoved:: Version [kurze Erklärung]¶

Ähnlich wie version-added, beschreibt aber, wann das Feature entfernt wurde. Eine Erklärung kann angegeben werden, um dem Leser mitzuteilen, was stattdessen verwendet werden soll oder warum das Feature entfernt wurde.

Hinzugefügt in Version 7.3.

Geändert in Version 9.0: Die Direktive versionremoved wurde in version-removed umbenannt. Der vorherige Name bleibt als Alias erhalten.

Beispiel

.. version-removed:: 4.0
   The :py:func:`spam` function is more flexible, and should be used instead.

Entfernt in Version 4.0: Die Funktion spam() ist flexibler und sollte stattdessen verwendet werden.

Präsentational¶

.. rubric:: Titel¶

Eine Rubrik ist wie eine informelle Überschrift, die nicht zur Struktur des Dokuments passt, d.h. sie erstellt keinen Knoten im Inhaltsverzeichnis.

Hinweis

Wenn der *Titel* der Rubrik „Fußnoten“ (oder das Äquivalent in der ausgewählten Sprache) ist, wird diese Rubrik vom LaTeX-Writer ignoriert, da angenommen wird, dass sie nur Fußnotendefinitionen enthält und daher eine leere Überschrift erstellen würde.

Optionen

:class: Klassennamen (eine Liste von Klassennamen, durch Leerzeichen getrennt)¶: Weisen Sie Klassenattribute zu. Dies ist eine allgemeine Option.

:name: Label (Text)¶: Ein impliziter Zielname, auf den mit der ref-Rolle verwiesen werden kann. Dies ist eine allgemeine Option.

:heading-level: n (Zahl von 1 bis 6)¶: Hinzugefügt in Version 7.4.1.

Verwenden Sie diese Option, um die Überschriftenebene der Rubrik anzugeben. In diesem Fall wird die Rubrik für die HTML-Ausgabe als <h1> bis <h6> gerendert oder als das entsprechende nicht nummerierte Abschnittsbefehl für LaTeX (siehe latex_toplevel_sectioning).

.. centered::¶: Diese Direktive erstellt eine zentrierte, fettgedruckte Textzeile.

Veraltet seit Version 1.1: Diese reine Präsentationsdirektive ist ein Relikt aus älteren Versionen. Verwenden Sie stattdessen eine rst-class-Direktive und fügen Sie eine entsprechende Formatierung hinzu.

.. hlist::¶

Diese Direktive muss eine Aufzählung enthalten. Sie wandelt sie in eine kompaktere Liste um, indem entweder mehr als ein Element horizontal verteilt oder der Abstand zwischen den Elementen verringert wird, abhängig vom Builder.

Optionen

:columns: n (int)¶

Die Anzahl der Spalten; Standard ist 2. Zum Beispiel

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally

Hinzugefügt in Version 0.6.

Codebeispiele anzeigen¶

Es gibt mehrere Möglichkeiten, syntaktisch hervorgehobene wörtliche Codeblöcke in Sphinx anzuzeigen

Verwendung von reStructuredText Doctest-Blöcken;
mittels reStructuredText-Literalblöcke, optional in Kombination mit der highlight-Direktive;
mittels der code-block-Direktive;
und mittels der literalinclude-Direktive.

Doctest-Blöcke können nur verwendet werden, um interaktive Python-Sitzungen anzuzeigen, während die übrigen drei für andere Sprachen verwendet werden können. Von diesen dreien sind Literalblöcke nützlich, wenn ein gesamtes Dokument oder zumindest große Teile davon Codeblöcke mit der gleichen Syntax verwenden und auf die gleiche Weise gestaltet werden sollen. Auf der anderen Seite ist die code-block-Direktive sinnvoller, wenn Sie eine feinere Kontrolle über die Gestaltung jedes Blocks wünschen oder wenn ein Dokument Codeblöcke mit mehreren unterschiedlichen Syntaxen enthält. Schließlich ist die literalinclude-Direktive nützlich, um vollständige Code-Dateien in Ihre Dokumentation einzufügen.

In allen Fällen wird die Syntaxhervorhebung von Pygments bereitgestellt. Bei der Verwendung von Literalblöcken wird dies mithilfe von highlight-Direktiven in der Quelldatei konfiguriert. Wenn eine highlight-Direktive angetroffen wird, wird diese verwendet, bis die nächste highlight-Direktive angetroffen wird. Wenn keine highlight-Direktive in der Datei vorhanden ist, wird die globale Hervorhebungssprache verwendet. Diese ist standardmäßig auf python eingestellt, kann aber mit dem Konfigurationswert highlight_language konfiguriert werden. Die folgenden Werte werden unterstützt

none (keine Hervorhebung)
default (ähnlich wie python3, aber mit einem Fallback auf none ohne Warnung, falls die Hervorhebung fehlschlägt; der Standardwert, wenn highlight_language nicht gesetzt ist)
guess (Pygments lässt den Lexer basierend auf dem Inhalt erraten, funktioniert nur mit bestimmten gut erkennbaren Sprachen)
python
rest
c
… und jeder andere Lexer-Alias, den Pygments unterstützt

Wenn die Hervorhebung mit der ausgewählten Sprache fehlschlägt (d.h. Pygments gibt ein „Error“-Token aus), wird der Block überhaupt nicht hervorgehoben.

Wichtig

Die Liste der unterstützten Lexer-Aliase hängt von der Pygments-Version ab. Wenn Sie eine konsistente Hervorhebung sicherstellen möchten, sollten Sie Ihre Pygments-Version fixieren.

.. highlight:: language¶

Beispiel

.. highlight:: c

Diese Sprache wird verwendet, bis die nächste highlight-Direktive angetroffen wird. Wie bereits besprochen, kann language jeder von Pygments unterstützte Lexer-Alias sein.

Optionen

:linenothreshold: threshold (number (optional))¶

Aktiviert die Generierung von Zeilennummern für Codeblöcke.

Diese Option nimmt eine optionale Zahl als Schwellenwertparameter an. Wenn ein Schwellenwert angegeben wird, erzeugt die Direktive nur Zeilennummern für Codeblöcke, die länger als N Zeilen sind. Wenn keiner angegeben wird, werden Zeilennummern für alle Codeblöcke erzeugt.

Beispiel

.. highlight:: python
   :linenothreshold: 5

:force: (no value)¶: Wenn angegeben, werden kleinere Fehler bei der Hervorhebung ignoriert.

Hinzugefügt in Version 2.1.

.. code-block:: [language]¶

.. sourcecode:: [language]¶

.. code:: [language]¶

Beispiel

.. code-block:: ruby

   Some Ruby code.

Der Aliasname der Direktive sourcecode funktioniert ebenfalls. Diese Direktive nimmt einen Sprachnamen als Argument. Dies kann jeder von Pygments unterstützte Lexer-Alias sein. Wenn er nicht angegeben wird, wird die Einstellung der highlight-Direktive verwendet. Wenn diese nicht gesetzt ist, wird highlight_language verwendet. Um ein Codebeispiel *inline* innerhalb anderen Textes anzuzeigen, anstatt als separaten Block, können Sie stattdessen die code-Rolle verwenden.

Changed in version 2.0: Das Argument language wird optional.

Optionen

:linenos: (no value)¶

Aktiviert die Generierung von Zeilennummern für den Codeblock.

.. code-block:: ruby
   :linenos:

   Some more Ruby code.

:lineno-start: number (number)¶

Legt die erste Zeilennummer des Codeblocks fest. Wenn vorhanden, wird die Option linenos ebenfalls automatisch aktiviert.

.. code-block:: ruby
   :lineno-start: 10

   Some more Ruby code, with line numbering starting at 10.

Hinzugefügt in Version 1.3.

:emphasize-lines: line numbers (comma separated numbers)¶

Betont bestimmte Zeilen des Codeblocks.

.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print('This line is highlighted.')
       print('This one is not...')
       print('...but this one is.')

Hinzugefügt in Version 1.1.

Changed in version 1.6.6: LaTeX unterstützt die Option emphasize-lines.

:force: (no value)¶: Ignoriert kleinere Fehler bei der Hervorhebung.

Hinzugefügt in Version 2.1.

:caption: caption of code block (text)¶: Legt eine Bildunterschrift für den Codeblock fest.

Hinzugefügt in Version 1.3.

:name: a label for hyperlink (text)¶

Definiert einen impliziten Zielnamen, auf den mit der ref-Rolle verwiesen werden kann. Zum Beispiel

.. code-block:: python
   :caption: this.py
   :name: this-py

   print('Explicit is better than implicit.')

Um einen Codeblock mittels der ref- oder der numref-Rolle zu referenzieren, müssen sowohl name als auch caption definiert sein. Das Argument von name kann dann an numref übergeben werden, um die Querverweisfunktion zu erzeugen. Beispiel

See :numref:`this-py` for an example.

Bei Verwendung von ref ist es möglich, eine Querverweisfunktion mit nur definiertem name zu erzeugen, vorausgesetzt, ein expliziter Titel wird angegeben. Beispiel

See :ref:`this code snippet <this-py>` for an example.

Hinzugefügt in Version 1.3.

:class: class names (a list of class names separated by spaces)¶: Weisen Sie Klassenattribute zu. Dies ist eine allgemeine Option.

Hinzugefügt in Version 1.4.

:dedent: number (number or no value)¶

Entfernt Einrückungszeichen aus dem Codeblock. Wenn eine Zahl angegeben wird, werden die führenden N Zeichen entfernt. Wenn kein Argument angegeben wird, werden führende Leerzeichen über textwrap.dedent() entfernt. Zum Beispiel

.. code-block:: ruby
   :linenos:
   :dedent: 4

       some ruby code

Hinzugefügt in Version 1.3.

Changed in version 3.5: Automatische Dedentierung wird unterstützt.

.. literalinclude:: filename¶

Längere Darstellungen von unverändertem Text können eingefügt werden, indem der Beispieltext in einer externen Datei gespeichert wird, die nur reinen Text enthält. Die Datei kann mit der literalinclude-Direktive eingebunden werden. [3] Um beispielsweise die Python-Quelldatei example.py einzufügen, verwenden Sie

.. literalinclude:: example.py

Der Dateiname ist normalerweise relativ zum Pfad der aktuellen Datei. Wenn er jedoch absolut ist (beginnend mit /), ist er relativ zum obersten Quellverzeichnis.

Allgemeine Optionen

:class: class names (a list of class names, separated by spaces)¶: Weisen Sie Klassenattribute zu. Dies ist eine allgemeine Option.

Hinzugefügt in Version 1.4.

:name: label (text)¶: Ein impliziter Zielname, auf den mit der ref-Rolle verwiesen werden kann. Dies ist eine allgemeine Option.

Hinzugefügt in Version 1.3.

:caption: caption (text)¶: Fügt eine Bildunterschrift über dem eingefügten Inhalt hinzu. Wenn kein Argument angegeben wird, wird der Dateiname als Bildunterschrift verwendet.

Hinzugefügt in Version 1.3.

Optionen für die Formatierung

:dedent: number (number or no value)¶: Entfernt Einrückungszeichen aus dem eingefügten Inhalt. Wenn eine Zahl angegeben wird, werden die führenden N Zeichen entfernt. Wenn kein Argument angegeben wird, wird die gesamte gemeinsame führende Einrückung entfernt (mittels textwrap.dedent()).

Hinzugefügt in Version 1.3.

Changed in version 3.5: Automatische Dedentierung wird unterstützt.

:tab-width: N (number)¶: Erweitert Tabs zu N Leerzeichen.

Hinzugefügt in Version 1.0.

:encoding: (text)¶

Gibt explizit die Zeichenkodierung der Datei an. Dies überschreibt die Standardkodierung (UTF-8). Zum Beispiel

.. literalinclude:: example.txt
   :encoding: latin-1

Added in version 0.4.3.

:linenos: (no value)¶: Zeigt Zeilennummern neben dem eingefügten Inhalt an. Standardmäßig werden die Zeilennummern ab 1 gezählt. Dies kann durch die Optionen :lineno-start: und :lineno-match: geändert werden.

:lineno-start: number (number)¶: Legt die Zeilennummer für die erste anzuzeigende Zeile fest. Wenn angegeben, aktiviert dies automatisch :linenos:.

:lineno-match:¶: Beim Einfügen nur von Teilen einer Datei und Anzeigen der ursprünglichen Zeilennummern. Dies ist nur zulässig, wenn die Auswahl aus zusammenhängenden Zeilen besteht.

Hinzugefügt in Version 1.3.

:emphasize-lines: line numbers (comma separated numbers)¶

Betont bestimmte Zeilen des eingefügten Inhalts. Zum Beispiel

.. literalinclude:: example.txt
   :emphasize-lines: 1,2,4-6

:language: language (text)¶: Wählt eine Hervorhebungssprache (Pygments-Lexer) aus, die sich von der Standardsprache der aktuellen Datei unterscheidet (gesetzt durch highlight oder highlight_language).

:force: (no value)¶: Ignoriert kleinere Fehler bei der Hervorhebung.

Hinzugefügt in Version 2.1.

Optionen zur Auswahl des einzufügenden Inhalts

:pyobject: object (text)¶

Für Python-Dateien nur die angegebene Klasse, Funktion oder Methode einfügen.

.. literalinclude:: example.py
   :pyobject: Timer.start

Hinzugefügt in Version 0.6.

:lines: line numbers (comma separated numbers)¶

Gibt genau an, welche Zeilen eingefügt werden sollen.

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

Dies schließt Zeile 1, Zeile 3, Zeilen 5 bis 10 und Zeile 20 bis zum Ende ein.

Hinzugefügt in Version 0.6.

:start-at: text¶

:start-after: text¶

:end-before: text¶

:end-at: text¶

Eine andere Möglichkeit, zu steuern, welcher Teil der Datei eingefügt wird, ist die Verwendung der Optionen start-after und end-before (oder nur einer davon). Wenn start-after als String-Option angegeben wird, werden nur die Zeilen eingefügt, die nach der ersten Zeile mit diesem String folgen. Wenn end-before als String-Option angegeben wird, werden nur die Zeilen eingefügt, die vor der ersten Zeile mit diesem String liegen. Die Optionen start-at und end-at verhalten sich ähnlich, aber die Zeilen, die den übereinstimmenden String enthalten, werden eingefügt.

start-after/start-at und end-before/end-at können denselben String haben. start-after/start-at filtern Zeilen vor der Zeile, die den Optionsstring enthält (start-at behält die Zeile). Dann filtern end-before/end-at Zeilen nach der Zeile, die den Optionsstring enthält (end-at behält die Zeile und end-before überspringt die erste Zeile).

Added in version 0.6: Hinzugefügt wurden die Optionen start-after und end-before.

Added in version 1.5: Hinzugefügt wurden die Optionen start-at und end-at.

Tipp

Um nur den [second-section] einer INI-Datei wie der folgenden auszuwählen, verwenden Sie :start-at: [second-section] und :end-before: [third-section]

[first-section]
var_in_first=true

[second-section]
var_in_second=true

[third-section]
var_in_third=true

Diese Optionen können bei der Arbeit mit Tag-Kommentaren nützlich sein. Mit :start-after: [initialise] und :end-before: [initialised] werden die Zeilen zwischen den beiden Kommentaren unten beibehalten

if __name__ == "__main__":
    # [initialise]
    app.start(":8000")
    # [initialised]

Wenn Zeilen auf eine der oben beschriebenen Arten ausgewählt wurden, beziehen sich die Zeilennummern in emphasize-lines auf diese ausgewählten Zeilen, die fortlaufend ab 1 gezählt werden.

:prepend: line (text)¶: Fügt eine Zeile vor dem eingefügten Code ein. Dies kann beispielsweise nützlich sein, wenn PHP-Code hervorgehoben wird, der die Marker <?php oder ?> nicht enthält.

Hinzugefügt in Version 1.0.

:append: line (text)¶: Fügt eine Zeile nach dem eingefügten Code an. Dies kann beispielsweise nützlich sein, wenn PHP-Code hervorgehoben wird, der die Marker <?php oder ?> nicht enthält.

Hinzugefügt in Version 1.0.

:diff: filename¶

Zeigt den Unterschied zwischen zwei Dateien an. Zum Beispiel

.. literalinclude:: example.txt
   :diff: example.txt.orig

Dies zeigt den Unterschied zwischen example.txt und example.txt.orig im einheitlichen Diff-Format.

Hinzugefügt in Version 1.3.

Changed in version 0.6: Unterstützung für absolute Dateinamen hinzugefügt.

Changed in version 1.6: Wenn sowohl start-after als auch lines verwendet werden, wird die erste Zeile gemäß start-after als Zeilennummer 1 für lines betrachtet.

Glossar¶

.. glossary::¶

Diese Direktive muss eine reStructuredText-Definitionlisten-ähnliche Markup mit Begriffen und Definitionen enthalten. Die Definitionen sind dann mit der term-Rolle referenzierbar. Beispiel

.. glossary::

   environment
      A structure where information about all documents under the root is
      saved, and used for cross-referencing.  The environment is pickled
      after the parsing stage, so that successive runs only need to read
      and parse new and changed documents.

   source directory
      The directory which, including its subdirectories, contains all
      source files for one Sphinx project.

Im Gegensatz zu regulären Definitionslisten sind mehrere Begriffe pro Eintrag erlaubt, und Inline-Markup ist in Begriffen erlaubt. Sie können auf alle Begriffe verlinken. Zum Beispiel

.. glossary::

   term 1
   term 2
      Definition of both terms.

(Wenn das Glossar sortiert ist, bestimmt der erste Begriff die Sortierreihenfolge.)

Wenn Sie einen „Gruppierungsschlüssel“ für allgemeine Indexeinträge angeben möchten, können Sie einen „Schlüssel“ als „Begriff : Schlüssel“ setzen. Zum Beispiel

.. glossary::

   term 1 : A
   term 2 : B
      Definition of both terms.

Beachten Sie, dass „Schlüssel“ als solcher für den Gruppierungsschlüssel verwendet wird. Der „Schlüssel“ wird nicht normalisiert; die Schlüssel „A“ und „a“ werden zu unterschiedlichen Gruppen. Die gesamten Zeichen in „Schlüssel“ werden anstelle des ersten Zeichens verwendet; dies wird für die Gruppierungsschlüssel „Combining Character Sequence“ und „Surrogate Pairs“ verwendet.

In i18n-Situationen können Sie „lokalisierter Begriff : Schlüssel“ angeben, auch wenn der Originaltext nur den Teil „Begriff“ enthält. In diesem Fall wird der übersetzte „lokalisierte Begriff“ in der Gruppe „Schlüssel“ kategorisiert.

Changed in version 1.1: Unterstützt nun mehrere Begriffe und Inline-Markup in Begriffen.

Changed in version 1.4: Index-Schlüssel für Glossarbegriffe gelten als experimentell.

Optionen

:sorted:¶: Sortiert die Einträge alphabetisch.

Hinzugefügt in Version 0.6.

Changed in version 4.4: In internationalisierten Dokumentationen wird nach übersetzten Begriffen sortiert.

Meta-Informationen-Markup¶

.. sectionauthor:: name <email>¶

Identifiziert den Autor des aktuellen Abschnitts. Das Argument sollte den Namen des Autors enthalten, so dass er zur Darstellung und als E-Mail-Adresse verwendet werden kann. Der Domain-Name des Adressaten sollte klein geschrieben sein. Beispiel

.. sectionauthor:: Guido van Rossum <[email protected]>

Standardmäßig wird dieses Markup in der Ausgabe nicht reflektiert (es hilft, Beiträge zu verfolgen), aber Sie können den Konfigurationswert show_authors auf True setzen, um sie in der Ausgabe als Absatz zu erzeugen.

.. codeauthor:: name <email>¶: Die codeauthor-Direktive, die mehrmals vorkommen kann, nennt die Autoren des beschriebenen Codes, genauso wie sectionauthor die(die) Autoren eines Dokumentationsstücks nennt. Auch sie erzeugt nur dann eine Ausgabe, wenn der Konfigurationswert show_authors auf True gesetzt ist.

Indexgenerierendes Markup¶

Sphinx erstellt automatisch Indexeinträge aus allen Objektbeschreibungen (wie Funktionen, Klassen oder Attributen), wie in Domains besprochen.

Es gibt jedoch auch explizites Markup, um den Index umfassender zu gestalten und Indexeinträge in Dokumenten zu ermöglichen, in denen Informationen nicht hauptsächlich in Informationseinheiten enthalten sind, wie z.B. der Sprachreferenz.

.. index:: <entries>¶

Diese Direktive enthält einen oder mehrere Indexeinträge. Jeder Eintrag besteht aus einem Typ und einem Wert, die durch einen Doppelpunkt getrennt sind.

Zum Beispiel

.. index::
   single: execution; context
   pair: module; __main__
   pair: module; sys
   triple: module; search; path
   seealso: scope

The execution context
---------------------

...

Diese Direktive enthält fünf Einträge, die in den generierten Index als Einträge umgewandelt werden, die auf die exakte Stelle der Indexanweisung verweisen (oder im Falle von Offline-Medien auf die entsprechende Seitenzahl).

Da Index-Direktiven Querverweisziele an ihrer Position im Quelltext erzeugen, ist es sinnvoll, sie *vor* dem Element zu platzieren, auf das sie sich beziehen – z.B. eine Überschrift, wie im obigen Beispiel.

Die möglichen Eintragsarten sind

single

Erstellt einen einzelnen Indexeintrag. Kann durch Trennung des Untereintrags mit einem Semikolon zu einem Untereintrag gemacht werden (diese Notation wird auch unten verwendet, um zu beschreiben, welche Einträge erstellt werden). Beispiele

.. index:: single: execution
           single: execution; context

single: execution erstellt einen Indexeintrag mit der Bezeichnung execution.
single: execution; context erstellt einen Untereintrag von execution mit der Bezeichnung context.

pair

Eine Abkürzung zum Erstellen von zwei Indexeinträgen. Das Wertepaar muss durch ein Semikolon getrennt sein. Beispiel

.. index:: pair: loop; statement

Dies würde zwei Indexeinträge erstellen; loop; statement und statement; loop.

triple

Eine Abkürzung zum Erstellen von drei Indexeinträgen. Alle drei Werte müssen durch ein Semikolon getrennt sein. Beispiel

.. index:: triple: module; search; path

Dies würde drei Indexeinträge erstellen; module; search path, search; path, module und path; module search.

see

Eine Abkürzung zum Erstellen eines Indexeintrags, der auf einen anderen Eintrag verweist. Beispiel

.. index:: see: entry; other

Dies würde einen Indexeintrag erstellen, der von entry auf other verweist (d.h. ‚entry‘: Siehe ‚other‘).

seealso

Wie see, aber fügt „siehe auch“ anstelle von „siehe“ ein.

module, keyword, operator, object, exception, statement, builtin

Diese **veralteten** Abkürzungen erstellen alle zwei Indexeinträge. Zum Beispiel erstellt module: hashlib die Einträge module; hashlib und hashlib; module.

Deprecated since version 1.0: Diese Python-spezifischen Eintragsarten sind veraltet.

Changed in version 7.1: Die Entfernungsvariante wurde auf Sphinx 9.0 gesetzt. Die Verwendung dieser Eintragsarten gibt nun Warnungen mit der Kategorie index aus.

Sie können „Haupt“-Indexeinträge markieren, indem Sie ihnen ein Ausrufezeichen voranstellen. Die Verweise auf „Haupt“-Einträge werden im generierten Index hervorgehoben. Wenn beispielsweise zwei Seiten Folgendes enthalten

.. index:: Python

und eine Seite Folgendes enthält

.. index:: ! Python

dann wird der Rückverweis auf die letztere Seite unter den drei Rückverweisen hervorgehoben.

Für Index-Direktiven, die nur „single“-Einträge enthalten, gibt es eine Kurzschreibweise

.. index:: BNF, grammar, syntax, notation

Dies erstellt vier Indexeinträge.

Changed in version 1.1: Hinzugefügt wurden die Typen see und seealso sowie die Markierung von Haupt-Einträgen.

Optionen

:name: a label for hyperlink (text)¶

Definiert einen impliziten Zielnamen, auf den mit der ref-Rolle verwiesen werden kann. Zum Beispiel

.. index:: Python
   :name: py-index

Hinzugefügt in Version 3.0.

:index:¶

Während die index-Direktive eine Block-Ebene-Markup ist und auf den Anfang des nächsten Absatzes verweist, gibt es auch eine entsprechende Rolle, die das Linkziel direkt dort setzt, wo sie verwendet wird.

Der Inhalt der Rolle kann eine einfache Phrase sein, die dann im Text verbleibt und als Indexeintrag verwendet wird. Er kann auch eine Kombination aus Text und Indexeintrag sein, wie bei expliziten Zielen von Querverweisen. In diesem Fall kann der „Ziel“-Teil ein vollständiger Eintrag sein, wie für die Direktive oben beschrieben. Zum Beispiel

This is a normal reStructuredText :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.

Hinzugefügt in Version 1.1.

Inhalt basierend auf Tags einschließen¶

.. only:: <expression>¶

Fügt den Inhalt der Direktive nur ein, wenn der *Ausdruck* wahr ist. Der Ausdruck sollte aus Tags bestehen, wie hier

.. only:: html and draft

Nicht definierte Tags sind falsch, definierte Tags sind wahr (Tags können über die --tag-Kommandozeilenoption oder innerhalb von conf.py definiert werden, siehe hier). Boolesche Ausdrücke (wie (latex or html) and draft) werden unterstützt und dürfen Klammern verwenden.

Das *Format* und der *Name* des aktuellen Builders (html, latex oder text) werden immer als Tag gesetzt [4]. Um die Unterscheidung zwischen Format und Name explizit zu machen, werden sie auch mit dem Präfix format_ und builder_ hinzugefügt, z.B. definiert der EPUB-Builder die Tags html, epub, format_html und builder_epub.

Diese Standard-Tags werden nach dem Einlesen der Konfigurationsdatei gesetzt, sodass sie dort nicht verfügbar sind.

Alle Tags müssen der Standard-Syntax für Python-Bezeichner folgen, wie sie in der Dokumentation zu den Bezeichnern und Schlüsselwörtern beschrieben ist. Das heißt, ein Tag-Ausdruck darf nur aus Tags bestehen, die der Syntax von Python-Variablen entsprechen. In ASCII besteht dies aus den Groß- und Kleinbuchstaben A bis Z, dem Unterstrich _ und, außer dem ersten Zeichen, den Ziffern 0 bis 9.

Hinzugefügt in Version 0.6.

Geändert in Version 1.2: Name des Builders und Präfixe hinzugefügt.

Warnung

Diese Direktive ist dazu gedacht, nur den Inhalt eines Dokuments zu steuern. Sie kann keine Sektionen, Labels usw. steuern.

Tabellen¶

Verwenden Sie reStructuredText-Tabellen, also entweder

Grid-Tabellensyntax (ref),
Simple-Tabellensyntax (ref),
csv-table-Syntax,
oder list-table-Syntax.

Die Direktive table dient als optionaler Wrapper für die Grid- und Simple-Syntaxen.

Sie funktionieren gut in HTML-Ausgaben, aber die Darstellung von Tabellen in LaTeX ist komplex. Überprüfen Sie die latex_table_style.

Geändert in Version 1.6: Zusammengeführte Zellen (mehrzeilig, mehrspaltig, beides) aus Grid-Tabellen, die komplexe Inhalte wie mehrere Absätze, Blockquotes, Listen, Literalblöcke enthalten, werden korrekt in LaTeX-Ausgaben gerendert.

Geändert in Version 9.0: Die teilweise Unterstützung des LaTeX-Builders für das Verschachteln einer Tabelle in einer anderen wurde erweitert. Zuvor gab Sphinx einen Fehler aus, wenn die Klasse longtable für eine Tabelle mit einer verschachtelten Tabelle angegeben wurde, und einige Fälle gaben auf Sphinx-Ebene keinen Fehler aus, sondern führten während des PDF-Builds auf LaTeX-Ebene zu Fehlern. Dies ist ein komplexes Thema im LaTeX-Rendering und die Ausgabe kann manchmal über die Direktive tabularcolumns verbessert werden.

.. tabularcolumns:: Spaltenspezifikation¶

Diese Direktive beeinflusst nur die LaTeX-Ausgabe und nur die nächste Tabelle in der Quelle. Das obligatorische Argument ist eine Spaltenspezifikation (im LaTeX-Jargon als „Alignment Preamble“ bezeichnet). Bitte konsultieren Sie eine LaTeX-Dokumentation, z. B. die Wiki-Seite, für die Grundlagen einer solchen Spaltenspezifikation.

Hinzugefügt in Version 0.3.

Sphinx rendert Tabellen mit höchstens 30 Zeilen mit tabulary (oder tabular, wenn mindestens eine Zelle entweder einen Codeblock oder eine verschachtelte Tabelle enthält) und solche mit mehr Zeilen mit longtable. Der Vorteil von tabulary ist, dass es versucht, geeignete Spaltenbreiten automatisch (intern in LaTeX) zu berechnen.

Der tabulary-Algorithmus funktioniert oft gut, aber in einigen Fällen, wenn eine Zelle lange Absätze enthält, erhält die Spalte eine große Breite, während andere Spalten, deren Zellen nur einzelne Wörter enthalten, zu schmal werden können. Die Direktive tabularcolumns kann helfen, dies zu lösen, indem sie LaTeX eine benutzerdefinierte „Alignment Preamble“ (auch „colspec“ genannt) zur Verfügung stellt. Zum Beispiel eignet sich lJJ für eine dreispaltige Tabelle, deren erste Spalte nur einzelne Wörter enthält und die anderen beiden lange Absätze in den Zellen haben.

Hinweis

Natürlich wäre eine vollständig automatisierte Lösung besser, und es wird immer noch darauf gehofft, aber es ist ein intrinsischer Aspekt von tabulary, und letzteres wird von Sphinx seit 0.3 verwendet... Es sieht so aus, als ob die Lösung des Problems von gequetschten Spalten erhebliche Änderungen an diesem LaTeX-Paket erfordern würde. Und eine gute Alternative scheint es derzeit (Stand 2025) nicht zu geben.

Hinweis

Eine Möglichkeit, das Problem für alle Tabellen gleichzeitig zu lösen, besteht darin, in der LaTeX-Präambel (siehe latex_elements) einen Befehl wie \setlength{\tymin}{1cm} einzufügen, der bewirkt, dass alle Spalten mindestens 1cm breit sind (abzüglich des Leerraums zwischen den Spalten). Derzeit konfiguriert Sphinx \tymin so, dass mindestens drei Zeichen Platz sind.

Hier ist eine anspruchsvollere „colspec“ für eine 4-Spalten-Tabelle

.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}

Dies wird in den eigenen PDF-Dokumenten von Sphinx unter Veraltete APIs verwendet. In Bezug auf Spaltenbreiten erreicht diese „colspec“ dasselbe wie die Option :widths: auf 40 10 12 38 gesetzt, injiziert aber zusätzliche Effekte.

Hinweis

Wenn sowohl die Direktive tabularcolumns als auch die Option :widths: von Tabellendirektiven verwendet werden, wird die Option :widths: vom LaTeX-Builder ignoriert. Andere Builder beachten sie natürlich.

Literalblöcke funktionieren überhaupt nicht mit tabulary und Sphinx greift dann auf die LaTeX-Umgebung tabular zurück. Die Spezifikation tabularcolumns wird in diesem Fall nur verwendet, wenn sie keine Verwendung der spezifischen tabulary-Spaltentypen enthält (nämlich L, R, C und J).

Neben den LaTeX-Spaltenspezifizierern l, r, c und p{width} und den tabulary-spezifischen L, R, C und J kann man auch (bei allen Tabellentypen) \X{a}{b} verwenden, das die Spaltenbreite als Bruch a/b der Gesamtzeilenbreite konfiguriert, und \Y{f}, wobei f eine Dezimalzahl ist: z. B. bedeutet \Y{0.2}, dass die Spalte 0.2 Mal die Zeilenbreite einnimmt.

Geändert in Version 1.6: Sphinx verwendet standardmäßig J (justifiziert) mit tabulary, nicht L (linksbündig). Um dies rückgängig zu machen, fügen Sie \newcolumntype{T}{L} in die LaTeX-Präambel ein, da Sphinx T verwendet und es standardmäßig als Alias für J festlegt.

Geändert in Version 9.0: Zuvor verwendete Sphinx tabulary nicht, wenn die Tabelle mindestens eine Zelle mit „problematischen“ Elementen wie Listen, Objektbeschreibungen, Blockquotes (usw.) enthielt, da solche Inhalte nicht ohne weiteres mit tabulary kompatibel sind. In Version 9.0 wurde eine Technik, die bereits für zusammengeführte Zellen verwendet wurde, auf solche Fälle erweitert, und die einzigen „problematischen“ Inhalte sind Codeblöcke und verschachtelte Tabellen. Tabellen, die (nur) Zellen mit mehreren Absätzen, Aufzählungs- oder nummerierten Listen oder Zeilenblöcken enthalten, passen nun besser zu ihrem Inhalt (wenn sie nicht von longtable gerendert werden). Zellen mit Objektbeschreibungen oder Ermahnungen führen immer noch dazu, dass die Tabelle die gesamte Textbreite einnimmt, aber Spalten in dieser Tabelle ohne solche Inhalte werden enger.

Hinweis

Um die Verwendung der LaTeX-Umgebung longtable zu erzwingen, übergeben Sie longtable als Option :class: an die Direktiven table, csv-table oder list-table. Verwenden Sie rst-class für andere Tabellen.

Mathematik¶

Die Eingabesprache für Mathematik ist LaTeX-Markup. Dies ist der De-facto-Standard für die Notationsweise von mathematischen Ausdrücken in Klartext und hat den zusätzlichen Vorteil, dass bei der Erstellung von LaTeX-Ausgaben keine weitere Übersetzung erforderlich ist.

Beachten Sie, dass Sie bei der Eingabe von mathematischem Markup in **Python-Docstrings**, die von autodoc gelesen werden, entweder alle Backslashes verdoppeln oder Python-Rohstrings (r"raw") verwenden müssen.

.. math::¶

Direktive für abgesetzte Mathematik (Mathematik, die die gesamte Zeile für sich beansprucht).

Die Direktive unterstützt mehrere Gleichungen, die durch eine Leerzeile getrennt werden sollten

.. math::

   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2

Zusätzlich wird jede einzelne Gleichung in einer split-Umgebung gesetzt, was bedeutet, dass Sie mehrere ausgerichtete Zeilen in einer Gleichung haben können, die bei & ausgerichtet und durch \\ getrennt sind.

.. math::

   (a + b)^2  &=  (a + b)(a + b) \\
              &=  a^2 + 2ab + b^2

Weitere Details finden Sie in der Dokumentation des AmSMath LaTeX-Pakets.

Wenn die Mathematik nur eine Textzeile ist, kann sie auch als Direktivenargument angegeben werden

.. math:: (a + b)^2 = a^2 + 2ab + b^2

Optionen

:class: Klassen- Namen (eine Liste von Klassennamen, durch Leerzeichen getrennt)¶: Weisen Sie Klassenattribute zu. Dies ist eine allgemeine Option.

:name: Label (Text)¶: Ein impliziter Zielname, auf den mit der ref-Rolle verwiesen werden kann. Dies ist eine allgemeine Option.

:label: Label (Text)¶: Normalerweise werden Gleichungen nicht nummeriert. Wenn Sie möchten, dass Ihre Gleichung eine Nummer erhält, verwenden Sie die Option label. Wenn diese angegeben wird, wählt sie ein internes Label für die Gleichung aus, über das sie referenziert werden kann, und bewirkt, dass eine Gleichungsnummer ausgegeben wird. Siehe eq für ein Beispiel. Der Nummerierungsstil hängt vom Ausgabeformat ab.

:no-wrap:¶

Verhindert das Einbetten der gegebenen Mathematik in eine Mathematik-Umgebung. Wenn Sie diese Option angeben, müssen Sie selbst sicherstellen, dass die Mathematik ordnungsgemäß eingerichtet ist. Zum Beispiel

.. math::
   :no-wrap:

   \begin{eqnarray}
      y    & = & ax^2 + bx + c \\
      f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

Geändert in Version 8.2: Die Direktivenoption :nowrap: wurde in :no-wrap: umbenannt.

Der vorherige Name wurde als Alias beibehalten, wird aber als veraltet gelten und in einer zukünftigen Version von Sphinx entfernt.

Siehe auch

Mathematikunterstützung für HTML-Ausgaben in Sphinx: Rendering-Optionen für Mathematik mit HTML-Buildern.
latex_engine: Erklärt, wie der LaTeX-Builder konfiguriert wird, um Unicode-Literale in mathematischem Markup zu unterstützen.

Darstellung von Grammatikproduktionen¶

Spezielle Markups sind für die Anzeige von Produktionen einer formalen Grammatik verfügbar. Das Markup ist einfach und versucht nicht, alle Aspekte von BNF (oder abgeleiteten Formen) zu modellieren, bietet aber genug, um kontextfreie Grammatiken so anzuzeigen, dass Verwendungen eines Symbols als Hyperlinks zur Definition des Symbols gerendert werden. Es gibt diese Direktive

.. productionlist:: [production_group]¶

Diese Direktive wird verwendet, um eine Gruppe von Produktionen einzuschließen. Jede Produktion wird auf einer einzelnen Zeile angegeben und besteht aus einem Namen, der durch einen Doppelpunkt vom folgenden Definitionstext getrennt ist. Wenn die Definition mehrere Zeilen umfasst, muss jede Fortsetzungszeile mit einem Doppelpunkt beginnen, der sich an derselben Spalte wie in der ersten Zeile befindet. Leerzeilen sind innerhalb von productionlist-Direktivenargumenten nicht erlaubt.

Das optionale Argument der Direktive production_group dient zur Unterscheidung verschiedener Sätze von Produktionslisten, die zu verschiedenen Grammatiken gehören. Mehrere Produktionslisten mit demselben production_group definieren somit Regeln im selben Geltungsbereich. Dies kann auch verwendet werden, um die Beschreibung einer langen oder komplexen Grammatik über mehrere productionlist-Direktiven mit demselben production_group aufzuteilen.

Die Definition kann Token-Namen enthalten, die als interpretierter Text markiert sind (z. B. „sum ::= `integer` "+" `integer`“), um Querverweise auf die Produktionen dieser Tokens zu generieren. Solche Querverweise beziehen sich implizit auf Produktionen aus der aktuellen Gruppe. Um eine Produktion aus einer anderen Grammatik zu referenzieren, muss der Token-Name mit dem Gruppennamen und einem Doppelpunkt vorangestellt werden, z. B. „other-group:sum“. Wenn die Gruppe des Tokens nicht in der Produktion angezeigt werden soll, kann sie mit einer Tilde vorangestellt werden, z. B. „~other-group:sum“. Um eine Produktion aus einer unbenannten Grammatik zu referenzieren, sollte der Token mit einem Doppelpunkt vorangestellt werden, z. B. „:sum“. Es erfolgt keine weitere reStructuredText-Analyse in der Produktion, sodass Sonderzeichen (*, | usw.) nicht maskiert werden müssen.

Token-Produktionen können außerhalb der Produktionsliste mit der token-Rolle referenziert werden. Wenn Sie ein production_group-Argument verwendet haben, muss der Token-Name mit dem Gruppennamen und einem Doppelpunkt vorangestellt werden, z. B. „my_group:sum“ anstelle von nur „sum“. Standardmäßige Cross-Referencing-Modifikatoren können mit der :token:-Rolle verwendet werden, wie z. B. benutzerdefinierter Linktext und das Unterdrücken des Gruppennamens mit einer Tilde (~).

Das Folgende ist ein Beispiel aus dem Python Reference Manual

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

Fußnoten