reStructuredText-Grundlagen

reStructuredText ist die standardmäßige Klartext-Auszeichnungssprache, die von Sphinx verwendet wird. Dieser Abschnitt ist eine kurze Einführung in die Konzepte und die Syntax von reStructuredText (reST), die Autoren genügend Informationen liefern soll, um produktiv Dokumente zu erstellen. Da reStructuredText als einfache, unauffällige Auszeichnungssprache konzipiert wurde, wird dies nicht allzu lange dauern.

Siehe auch

Die maßgebliche Benutzerdokumentation zu reStructuredText. Die „ref“-Links in diesem Dokument verweisen auf die Beschreibung der einzelnen Konstrukte in der reStructuredText-Referenz.

Absätze

Der Absatz (ref) ist der grundlegendste Block in einem reStructuredText-Dokument. Absätze sind einfach Textblöcke, die durch eine oder mehrere Leerzeilen getrennt sind. Wie in Python ist die Einrückung in reStructuredText wichtig, daher müssen alle Zeilen desselben Absatzes linksbündig auf derselben Einrückungsebene ausgerichtet sein.

Inline-Auszeichnung

Die Standard-Inline-Auszeichnung von reStructuredText ist recht einfach: Verwenden Sie

  • einen Stern: *Text* für Hervorhebung (Kursivschrift),

  • zwei Sterne: **Text** für starke Hervorhebung (Fettschrift) und

  • Backticks: ``Text`` für Codebeispiele.

Wenn Sterne oder Backticks in Fließtext vorkommen und mit Inline-Auszeichnungsbegrenzern verwechselt werden könnten, müssen sie mit einem Backslash maskiert werden.

Beachten Sie einige Einschränkungen dieser Auszeichnung

  • sie darf nicht verschachtelt werden,

  • Inhalt darf nicht mit Leerzeichen beginnen oder enden: * Text* ist falsch,

  • er muss durch Nicht-Wortzeichen vom umgebenden Text getrennt sein. Verwenden Sie ein mit Backslash maskiertes Leerzeichen, um dies zu umgehen: diesistein\ *einziges*\ Wort.

Diese Einschränkungen können in zukünftigen Versionen von Docutils aufgehoben werden.

Es ist auch möglich, einige dieser Inline-Auszeichnungen durch Rollen zu ersetzen oder zu erweitern. Weitere Informationen finden Sie unter Rollen.

Listen und Zitat-ähnliche Blöcke

Listen-Auszeichnung (ref) ist natürlich: stellen Sie einfach einen Stern an den Anfang eines Absatzes und rücken Sie ihn richtig ein. Das Gleiche gilt für nummerierte Listen; sie können auch automatisch nummeriert werden, indem ein #-Zeichen verwendet wird

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

Verschachtelte Listen sind möglich, aber beachten Sie, dass sie durch Leerzeilen von den übergeordneten Listenelementen getrennt sein müssen

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Definitionslisten (ref) werden wie folgt erstellt

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

Beachten Sie, dass der Begriff nicht mehr als eine Textzeile haben kann.

Zitat-Absätze (ref) werden erstellt, indem sie einfach stärker als die umgebenden Absätze eingerückt werden.

Zeilenblöcke (ref) sind eine Möglichkeit, Zeilenumbrüche beizubehalten

| These lines are
| broken exactly like in
| the source file.

Es gibt auch mehrere speziellere Blöcke

  • Feldlisten (ref, mit Vorbehalten in Feldlisten)

  • Optionslisten (ref)

  • Zitat-Literalblöcke (ref)

  • Doctest-Blöcke (ref)

Literalblöcke

Literal-Codeblöcke (ref) werden eingeführt, indem ein Absatz mit dem Sonderzeichen :: endet. Der Literalblock muss eingerückt sein (und, wie alle Absätze, von den umgebenden durch Leerzeilen getrennt sein)

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

Die Behandlung des ::-Zeichens ist intelligent

  • Wenn es als eigener Absatz vorkommt, wird dieser Absatz vollständig aus dem Dokument weggelassen.

  • Wenn es von Leerzeichen vorangestellt ist, wird das Zeichen entfernt.

  • Wenn es von Nicht-Leerzeichen vorangestellt ist, wird das Zeichen durch einen einzelnen Doppelpunkt ersetzt.

Auf diese Weise würde der zweite Satz im ersten Absatz des obigen Beispiels als „Der nächste Absatz ist ein Codebeispiel:“ gerendert.

Code-Hervorhebung kann für diese Literalblöcke dokumentenweit mit der Direktive highlight und projektweit mit der Konfigurationsoption highlight_language aktiviert werden. Die Direktive code-block kann verwendet werden, um die Hervorhebung blockweise festzulegen. Diese Direktiven werden später besprochen.

Doctest-Blöcke

Doctest-Blöcke (ref) sind interaktive Python-Sitzungen, die aus Docstrings kopiert und eingefügt wurden. Sie benötigen nicht die Syntax für Literalblöcke. Der Doctest-Block muss mit einer Leerzeile enden und sollte *nicht* mit einem ungenutzten Prompt enden

>>> 1 + 1
2

Tabellen

Für Gitternetztabellen (ref) müssen Sie das Zellengitter selbst „malen“. Sie sehen so aus

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

Einfache Tabellen (ref) sind einfacher zu schreiben, aber begrenzt: sie müssen mehr als eine Zeile enthalten, und die Zellen der ersten Spalte dürfen keine mehreren Zeilen enthalten. Sie sehen so aus

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

Zwei weitere Syntaxen werden unterstützt: CSV-Tabellen und Listen-Tabellen. Sie verwenden einen expliziten Markup-Block. Weitere Informationen finden Sie unter Tabellen.

Abschnitte

Abschnittsüberschriften (ref) werden erstellt, indem der Abschnittstitel mit einem Satzzeichen unter- (und optional über-)schrieben wird, mindestens so lang wie der Text

=================
This is a heading
=================

Normalerweise werden keinen Überschriftenebenen bestimmten Zeichen zugewiesen, da die Struktur aus der Abfolge der Überschriften bestimmt wird. Diese Konvention wird jedoch im Python Developer’s Guide für die Dokumentation verwendet, der Sie folgen können

  • # mit Überstrich, für Teile

  • * mit Überstrich, für Kapitel

  • = für Abschnitte

  • - für Unterabschnitte

  • ^ für Unter-Unterabschnitte

  • " für Absätze

Natürlich können Sie Ihre eigenen Markierungszeichen verwenden (siehe die reStructuredText-Dokumentation) und eine tiefere Verschachtelungsebene verwenden, aber bedenken Sie, dass die meisten Zielformate (HTML, LaTeX) eine begrenzte unterstützte Verschachtelungstiefe haben.

Feldlisten

Feldlisten (ref) sind Folgen von Feldern, die wie folgt ausgezeichnet sind

:fieldname: Field content

Sie werden häufig in der Python-Dokumentation verwendet

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

Sphinx erweitert das Standardverhalten von Docutils und fängt Feldlisten ab, die am Anfang von Dokumenten angegeben sind. Weitere Informationen finden Sie unter Feldlisten.

Rollen

Eine Rolle oder „benutzerdefinierte interpretierte Textrolle“ (ref) ist ein Inline-Stück expliziter Auszeichnung. Es bedeutet, dass der eingeschlossene Text auf eine bestimmte Weise interpretiert werden soll. Sphinx verwendet dies, um semantische Auszeichnungen und Querverweise auf Bezeichner bereitzustellen, wie im entsprechenden Abschnitt beschrieben. Die allgemeine Syntax lautet :rollenname:`Inhalt`.

Docutils unterstützt die folgenden Rollen

Siehe Rollen für von Sphinx hinzugefügte Rollen.

Explizite Auszeichnung

„Explizite Auszeichnung“ (ref) wird in reStructuredText für die meisten Konstrukte verwendet, die eine spezielle Behandlung benötigen, wie z. B. Fußnoten, speziell hervorgehobene Absätze, Kommentare und generische Direktiven.

Ein expliziter Markup-Block beginnt mit einer Zeile, die mit .. gefolgt von einem Leerzeichen beginnt und durch den nächsten Absatz auf derselben Einrückungsebene beendet wird. (Zwischen expliziter Auszeichnung und normalen Absätzen muss eine Leerzeile sein. Das mag alles etwas kompliziert klingen, ist aber intuitiv genug, wenn man es schreibt.)

Direktiven

Eine Direktive (ref) ist ein generischer Block expliziter Auszeichnung. Zusammen mit Rollen ist sie einer der Erweiterungsmechanismen von reStructuredText, und Sphinx nutzt sie intensiv.

Docutils unterstützt die folgenden Direktiven

  • Admonitions: attention, caution, danger, error, hint, important, note, tip, warning und die generische admonition. (Die meisten Themes stylen nur „note“ und „warning“ speziell.)

  • Bilder

    • image (siehe auch Bilder unten)

    • figure (ein Bild mit Beschriftung und optionaler Legende)

  • Zusätzliche Körper-Elemente

    • contents (ein lokales, d.h. nur für die aktuelle Datei, Inhaltsverzeichnis)

    • container (ein Container mit einer benutzerdefinierten Klasse, nützlich zum Erstellen einer äußeren <div> in HTML)

    • rubric (eine Überschrift ohne Bezug zur Dokumentenstruktur)

    • topic, sidebar (spezielle hervorgehobene Körper-Elemente)

    • parsed-literal (Literalblock, der Inline-Auszeichnungen unterstützt)

    • epigraph (ein Blockzitat mit optionaler Titelzeile)

    • highlights, pull-quote (Blockzitate mit eigenem Klassenattribut)

    • compound (ein zusammengesetzter Absatz)

  • Spezielle Tabellen

    • table (eine Tabelle mit Titel)

    • csv-table (eine Tabelle, generiert aus kommagetrennten Werten)

    • list-table (eine Tabelle, generiert aus einer Liste von Listen)

  • Spezielle Direktiven

    • raw (rohe Zielformat-Auszeichnung einfügen)

    • include (reStructuredText aus einer anderen Datei einbinden) – in Sphinx wird bei Angabe eines absoluten Pfads zur Include-Datei dieser als relativ zum Quellverzeichnis behandelt

    • class (weist dem nächsten Element ein Klassenattribut zu)

      Hinweis

      Wenn die Standarddomäne eine class-Direktive enthält, wird diese Direktive überschattet. Daher exportiert Sphinx sie als rst-class neu.

      Tipp

      Wenn Sie einer Direktive eine Klasse hinzufügen möchten, können Sie stattdessen die :class:-Option (Option) in Betracht ziehen, die von den meisten Direktiven unterstützt wird und eine kompaktere Notation ermöglicht.

  • HTML-Spezifika

  • Beeinflussung der Auszeichnung

    • default-role (eine neue Standardrolle festlegen)

    • role (eine neue Rolle erstellen)

    Da diese nur dateibasiert sind, ist es besser, die Sphinx-Funktionen zum Festlegen von default_role zu verwenden.

Warnung

Verwenden Sie *nicht* die Direktiven sectnum, header und footer.

Von Sphinx hinzugefügte Direktiven werden in Direktiven beschrieben.

Grundsätzlich besteht eine Direktive aus einem Namen, Argumenten, Optionen und Inhalt. (Behalten Sie diese Terminologie im Hinterkopf, sie wird im nächsten Kapitel zur Beschreibung benutzerdefinierter Direktiven verwendet.) Anhand dieses Beispiels,

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

function ist der Name der Direktive. Sie erhält hier zwei Argumente, den Rest der ersten Zeile und die zweite Zeile, sowie eine Option module (wie Sie sehen, werden Optionen in den Zeilen unmittelbar nach den Argumenten und durch Doppelpunkte gekennzeichnet angegeben). Optionen müssen auf derselben Ebene wie der Direktiveninhalt eingerückt sein.

Der Inhalt der Direktive folgt nach einer Leerzeile und ist relativ zum Beginn der Direktive eingerückt oder, wenn Optionen vorhanden sind, in der gleichen Weise wie die Optionen.

Seien Sie vorsichtig, da die Einrückung keine feste Anzahl von Leerzeichen ist, z. B. drei, sondern jede Anzahl von Leerzeichen. Dies kann überraschend sein, wenn eine feste Einrückung im gesamten Dokument verwendet wird und für Direktiven, die auf Leerzeichen empfindlich reagieren, einen Unterschied machen kann. Vergleichen Sie

.. code-block::
   :caption: A cool example

       The output of this line starts with four spaces.

.. code-block::

       The output of this line has no spaces at the beginning.

Im ersten Codeblock wurde die Einrückung für den Inhalt durch die Optionszeile auf drei Leerzeichen fixiert, folglich beginnt der Inhalt mit vier Leerzeichen. Im letzteren Fall wurde die Einrückung durch den Inhalt selbst auf sieben Leerzeichen fixiert, sodass er nicht mit einem Leerzeichen beginnt.

Bilder

reStructuredText unterstützt eine Bild-Direktive (ref), die wie folgt verwendet wird

.. image:: gnu.png
   (options)

Bei Verwendung innerhalb von Sphinx muss der angegebene Dateiname (hier gnu.png) entweder relativ zur Quellendatei sein oder absolut, was bedeutet, dass er relativ zum oberen Quellverzeichnis ist. Zum Beispiel könnte die Datei sketch/spam.rst auf das Bild images/spam.png als ../images/spam.png oder /images/spam.png verweisen.

Sphinx kopiert Bilddateien beim Erstellen automatisch in ein Unterverzeichnis des Ausgabeverzeichnisses (z. B. das Verzeichnis _static für HTML-Ausgabe).

Die Interpretation von Bildgrößenoptionen (width und height) ist wie folgt: Wenn die Größe keine Einheit hat oder die Einheit Pixel sind, wird die angegebene Größe nur für Ausgabekanäle beachtet, die Pixel unterstützen. Andere Einheiten (wie pt für Punkte) werden für HTML- und LaTeX-Ausgabe verwendet (letztere ersetzt pt durch bp, da dies die TeX-Einheit ist, sodass 72bp=1in ist).

Sphinx erweitert das Standardverhalten von Docutils, indem es einen Stern für die Dateierweiterung zulässt

.. image:: gnu.*

Sphinx sucht dann nach allen Bildern, die dem angegebenen Muster entsprechen, und ermittelt deren Typ. Jeder Builder wählt dann das beste Bild aus diesen Kandidaten aus. Wenn beispielsweise der Dateiname gnu.* angegeben wurde und die Dateien gnu.pdf und gnu.png im Quellbaum vorhanden waren, würde der LaTeX-Builder ersteres wählen, während der HTML-Builder letzteres bevorzugen würde. Unterstützte Bildtypen und die Priorität bei der Auswahl werden unter Builder definiert.

Beachten Sie, dass Bilddateinamen keine Leerzeichen enthalten sollten.

Geändert in Version 0.4: Unterstützung für Dateinamen hinzugefügt, die mit einem Stern enden.

Geändert in Version 0.6: Bildpfade können jetzt absolut sein.

Geändert in Version 1.5: LaTeX-Ziel unterstützt Pixel (Standard ist 96px=1in).

Fußnoten

Für Fußnoten (ref) verwenden Sie [#name]_, um die Fußnotenposition zu markieren, und fügen Sie den Fußnoteninhalt am Ende des Dokuments nach einer Überschrift „Fußnoten“ hinzu, wie hier

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

Sie können die Fußnoten auch explizit nummerieren ([1]_) oder automatisch nummerierte Fußnoten ohne Namen verwenden ([#]_).

Zitate

Standard-reStructuredText-Zitate (ref) werden unterstützt, mit der zusätzlichen Funktion, dass sie „global“ sind, d. h. alle Zitate können aus allen Dateien referenziert werden. Verwenden Sie sie so

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

Die Verwendung von Zitaten ähnelt der Verwendung von Fußnoten, jedoch mit einer Beschriftung, die nicht numerisch ist oder mit # beginnt.

Substitutionen

reStructuredText unterstützt „Substitutionen“ (ref), die Text- und/oder Auszeichnungsstücke sind, die im Text mit |name| referenziert werden. Sie werden wie Fußnoten mit expliziten Markup-Blöcken definiert, wie hier

.. |name| replace:: replacement *text*

oder hier

.. |caution| image:: warning.png
             :alt: Warning!

Siehe die reStructuredText-Referenz für Substitutionen für Details.

Wenn Sie einige Substitutionen für alle Dokumente verwenden möchten, legen Sie sie in rst_prolog oder rst_epilog ab oder legen Sie sie in eine separate Datei und binden Sie sie in alle Dokumente ein, in denen Sie sie verwenden möchten, mit der include-Direktive. (Stellen Sie sicher, dass die Include-Datei eine Dateiendung hat, die sich von der anderer Quellendateien unterscheidet, um zu vermeiden, dass Sphinx sie als eigenständiges Dokument findet.)

Sphinx definiert einige Standardsubstitutionen, siehe Substitutionen.

Kommentare

Jeder explizite Markup-Block, der keine gültige Markup-Konstruktion ist (wie die obigen Fußnoten), wird als Kommentar (ref) betrachtet. Zum Beispiel

.. This is a comment.

Sie können Text nach einem Kommentarbeginn einrücken, um mehrzeilige Kommentare zu bilden

..
   This whole indented block
   is a comment.

   Still in the comment.

HTML-Metadaten

Die meta-Direktive ermöglicht die Angabe des HTML-Metadaten-Elements einer Sphinx-Dokumentationsseite. Zum Beispiel erzeugt die Direktive

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

die folgende HTML-Ausgabe

<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">

Außerdem fügt Sphinx die im Meta-Tag angegebenen Schlüsselwörter zum Suchindex hinzu. Dabei wird das lang-Attribut des Meta-Elements berücksichtigt. Zum Beispiel fügt die Direktive

.. meta::
   :keywords: backup
   :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
   :keywords lang=de: bittediesenkeyfinden

die folgenden Wörter zu den Suchindizes von Builds mit unterschiedlichen Sprachkonfigurationen hinzu

  • pleasefindthiskey, pleasefindthiskeytoo zu englischen Builds;

  • bittediesenkeyfinden zu deutschen Builds;

  • backup zu Builds in allen Sprachen.

Quell-Encoding

Sphinx unterstützt Quellcodedateien, die in UTF-8 kodiert sind. Das bedeutet, dass der gesamte Bereich von Unicode-Zeichen direkt in reStructuredText verwendet werden kann.

Stolpersteine

Es gibt einige Probleme, auf die man beim Verfassen von reStructuredText-Dokumenten häufig stößt

  • Trennung von Inline-Auszeichnungen: Wie bereits erwähnt, müssen Inline-Auszeichnungsbereiche durch Nicht-Wortzeichen vom umgebenden Text getrennt sein. Sie müssen ein mit Backslash maskiertes Leerzeichen verwenden, um dies zu umgehen. Einzelheiten finden Sie in der Referenz.

  • Keine verschachtelte Inline-Auszeichnung: Etwas wie *siehe :func:`foo`* ist nicht möglich.