ReStructuredText-Tutorial

RestructuredText (RST) ist eine vereinfachte Auszeichnungssprache („markup language“), mit deren Hilfe Textdokumente aus einfachen Strukturmerkmalen erzeugt werden können. Diese lassen sich dann mittels eines geeigneten Converters, z.B. Sphinx, automatisiert in LaTeX- oder HTML-Code übersetzen.

Um eine Datei mit RestructuredText-Inhalten zu erstellen, genügt es eine neue Textdatei mit einem Editor zu öffnen. Üblicherweise werden RestructuredText-Dateien mit der Endung .rst versehen.

Überschriften und Hervorhebungen

Überschriften sind zur Untergliederung eines Dokuments hilfreich und ermöglichen eine automatische Erzeugung von Inhaltsverzeichnissen. RestructuredText kennt dabei folgende Unterteilungen.

Beispiel:

Name eines Kapitels
===================

Name eines Abschnitts
---------------------

Name eines Unterabschnitts
^^^^^^^^^^^^^^^^^^^^^^^^^^

Name eines Paragraphen
''''''''''''''''''''''

Ergebnis:



Name eines Kapitels




Name eines Abschnitts




Name eines Unterabschnitts




Name eines Paragraphen

Zur Hervorhebung einer Überschrift muss somit nur die jeweilige Zeile durch eine zweite, ebenso lange Zeile mit entsprechenden Zeichen markiert werden; anschließend muss eine leere Zeile folgen.

Die Überschriften werden – je nach Converter und entsprechenden Einstellungen – in den erzeugten HTML- beziehungsweise PDF-Dateien mit unterschiedlicher Schriftgröße und/oder nummeriert dargestellt. In PDF-Dateien wird automatisch ein Inhaltsverzeichnis zu Beginn des Dokuments erzeugt, in HTML-Dateien wird das Inhaltsverzeichnis üblicherweise in der Seitenleiste angezeigt.

Zusätzlich ist es möglich, kleine Überschriften ohne Nummerierung und Auflistung im Inhaltsverzeichnis einzufügen. Hierfür wird eine so genannte „Direktive“ namens .. rubric:: verwendet.[1]

Beispiel:

Kapitelname
===========

Text.


.. rubric:: Bezeichnung

Mehr Text..

Eine weitere Aufgliederung eines Kapitels ist durch ein Aufspalten in mehrere Dateien möglich.

Das Inhaltsverzeichnis

Üblicherweise werden für die einzelnen Kapitel einer Dokumentation eigene Dateien angelegt, deren Namen in etwa den jeweiligen Kapitelüberschriften entsprechen sollten (auf Umlaute im Dateinamen sollte dabei verzichtet werden, Leerzeichen durch Binde- oder Unterstriche ersetzt werden). Jede dieser Dateien muss unmittelbar mit einer Kapitelüberschrift beginnen und kann weitere Überschriften beinhalten.

In der Hauptdatei index.rst der Dokumentation, die im Hauptverzeichnis zu finden ist, wird auf die einzelnen Kapitel über ein Inhaltsverzeichnus verwiesen. Um ein Inhaltsverzeichnis zu erzeugen, wird die so genannte „toctree“-Umgebung verwendet („Table-of-Contents“). Die Syntax dabei ist folgende:

.. toctree::
    :maxdepth: 2

    kapitelname-1.rst
    kapitelname-2.rst
    kapitelname-3.rst

Durch die Option :maxdepth: wird festgelegt, bis zu welcher Hierarchie-Stufe das Inhaltsverzeichnis aufgegliedert werden soll. Mit :maxdepth: 2 werden beispielsweise alle Kapitel- und Abschnittsnamen eingeblendet, die in den angegebenen Dateien zu finden sind. In der HTML-Version wird für jede toctree angegebene Datei eine neue Seite inklusive Rahmen und Navigationshilfen erzeugt. In der LaTeX-Version werden die im toctree angegeben Dateien der Reihe nach eingebunden, als ob sich ihre Inhalte hintereinander in einer einzigen Datei befänden.

Ein besonderer Vorteil dieser Methode liegt darin, dass umfangreichere Kapitel beliebig in weitere Unterkapitel aufgeteilt werden können:

  • Als erstes wird ein neuer Ordner angelegt, der den gleichen Namen wie die zugehörige RestructuredText-Datei erhält, beispielsweise kapitelname-2.
  • Anschließend wird die Kapitel-Datei in den neuen Ordner verschoben und dort in index.rst umbenannt.
  • Für jedes Unterkapitel wird in dem neuen Ordner eine neue Textdatei angelegt, deren Namen wiederum in etwa den Überschriften der einzelnen Abschnitte entsprechen sollten. Jeder Abschnitt wird dann aus der index.rst ausgeschnitten und in die entsprechende Datei eingefügt.
  • In die index.rst wird schließlich ein toctree angelegt, der die Namen aller Dateien, aus denen das Kapitel besteht, beinhaltet.

Von welcher Hierarchie-Ebene die Überschriften in den einzelnen Dateien ausgehen, ist nicht von Bedeutung: Beim Konvertieren der Quelltexte nach HTML oder PDF werden alle Hierarchie-Ebenen bei Bedarf automatisch angepasst. Es muss lediglich innerhalb jeder Datei darauf geachtet werden, dass unmittelbar mit der „höchste“ Überschrifts-Ebene begonnen wird. Eine Empfehlung hierfür ist, jede Datei mit einer Kapitelüberschrift zu beginnen und bei Bedarf weitere Überschriften einzufügen.

Kommentare

RestructuredText-Dateien können um Kommentare ergänzt werden, die bei der Übersetzung in PDF- beziehungsweise HTML-Dateien ignoriert werden und somit lediglich als „private“ Notizen für den Autor dienen.

Jede Zeile einer RST-Datei kann, indem zu Beginn zwei Punkte und (mindestens) ein Leerzeichen eingefügt werden, zu einem Kommentar gemacht werden.

Beispiel:

..  Dies hier ist ein Kommentar.

Um einen längeren, aus mehreren Zeilen bestehenden Kommentar zu erzeugen, kann einerseits jede Zeile einzeln durch zwei Punkte und ein Leerzeichen am Anfang der Zeile auskommentiert werden. Einfacher ist es, einen „langen Kommentar“ durch eine separate Zeile einzuleiten, die nur aus zwei Punkten und zwei Leerzeichen besteht:

Beispiel:

..
    Dies hier ist ein langer Kommentar.
    Er besteht aus mehreren Zeilen.

Auf diese Weise können auch mehrere Absätze auskommentiert werden. Hierbei muss jedoch in den Leerzeilen zwischen den Kommentar-Absätzen Leerzeichen oder Tabulatoren eingefügt werden, da lange Kommentare stets durch eine einzelne, komplett leere Zeile abgeschlossen werden.

Hervorhebung von Textstellen

Um eine einzelne Textstelle innerhalb eines Absatzes hervorzuheben, kann eine so genannte „Role“ verwendet werden.[2] Die wohl am häufigsten auftretenden Roles sind:

  • *Kursiver Text*:
    Eine Textstelle, die unmittelbar (ohne Leerzeichen) durch je ein Sternchen begrenzt ist, wird kursiv dargestellt.
  • **Fetter Text**:
    Eine Textstelle, die unmittelbar (ohne Leerzeichen) durch je zwei Sternchen begrenzt ist, wird fettgedruckt dargestellt.
  • ``Maschinenschrift``:
    Eine Textstelle, die unmittelbar (ohne Leerzeichen) durch je zwei schräge Apostrophen („Backticks“) begrenzt ist, wird in Maschinenschrift dargestellt. Diese Art der Hervorhebung kann insbesondere für kurze Codebeispiele genutzt werden.
  • :sub:`Text`:
    Eine Textstelle, die unmittelbar (ohne Leerzeichen) durch je einen schrägen Apostrophen („Backtick“) begrenzt ist und durch das einleitende Schlüsselwort :sub: oder :subscript: markiert ist, wird als tiefgestellter Text dargestellt.
  • :sup:`Text`:
    Eine Textstelle, die unmittelbar (ohne Leerzeichen) durch je einen schrägen Apostrophen („Backtick“) begrenzt ist und durch das einleitende Schlüsselwort :sub: markiert ist, wird als tiefgestellter Text dargestellt.

Beispiel:

Etwas *kursiv dargestellter*,
etwas **fettgedruckter** Text,
und etwas Text in ``Maschinenschrift``;

Tief gestellter Text: :sub:`123` und
hoch gestellter Text: :sup:`456`

Ergebnis:

Etwas kursiv dargestellter, etwas fettgedruckter Text, und etwas Text in Maschinenschrift.


Tief gestellter Text: 123 und hoch gestellter Text: 456

Mittels der :math:-Role können zusätzlich mathematische Formeln, geschrieben als LaTeX-Code, innerhalb einer Zeile eingefügt werden. Beispielsweise liefert :math:`a^2 + b^2 = c^2` als Ergebnis die Formel a^2 + b^2 = c^2.

Hervorhebung von Absätzen

Um einen Absatz beziehungsweise mehrere Absätze hervorzuheben, kann eine der folgenden Direktiven genutzt werden:

  • .. epigraph::

    Innerhalb einer epigraph-Umgebung werden gewöhnlich Zitate in das Dokument eingefügt. Am Ende wird dabei üblicherweise der Name des Autors der zitierten Textstelle angegeben.

    Beispiel:

    .. epigraph::

    "Phantasie ist wichtiger als Wissen, denn Wissen ist begrenzt."

    -- Albert Einstein

    Ergebnis:

    „Phantasie ist wichtiger als Wissen, denn Wissen ist begrenzt.“

    —Albert Einstein

    Innerhalb einer epigraph-Umgebung sind sowohl mehre Absätze als auch Inline-Markup (Roles) erlaubt. Die Ausgabe erfolgt eingerückt und mit reduzierter Zeilenlänge, um das Zitat gut erkennbar vom übrigen Text abzuheben; Zeilenumbrüche erfolgen automatisch.

  • .. line-block::

    Die line-block-Umgebung ist der epigraph-Umgebung ähnlich, jedoch finden im Ergebnis keine automatischen Zeilenumbrüche statt. Die Zeilen werden stattdessen in gleicher Form ausgegeben, wie sie innerhalb der line-block-Umgebung gesetzt werden. Dies ist insbesondere beim Zitieren von Gedichten und Versen nützlich:

    Beispiel:

    .. line-block::

    "Jede Blüte will zur Frucht
    Jeder Morgen Abend werden
    Ewiges ist nicht auf Erden
    Als der Wandel, als die Flucht."

    -- Hermann Hesse (Ausschnitt aus dem Gedicht "Welkes Blatt")

    Ergebnis:

    „Jede Blüte will zur Frucht
    Jeder Morgen Abend werden
    Ewiges ist nicht auf Erden
    Als der Wandel, als die Flucht.“

    – Hermann Hesse (Ausschnitt aus dem Gedicht „Welkes Blatt“)

    Absätze, die innerhalb einer line-block-Umgebung stehen, werden nicht automatisch eingerückt. Ist dies gewünscht, so kann man eine Einrückung entweder über entsprechende CSS-Einstellungen oder über eine manuelle Einrückung der jeweiligen Umgebung (Leerzeichen beziehungsweise Tabulatoren im Quellcode) erreichen.

  • note, hint, tip, warning, error, important

    Mit den obigen Direktiven lassen sich Infoboxen erzeugen. Der Titel der Infobox leitet sich dabei aus dem Direktivennamen ab (Bemerkung, Hinweis, Tip, Warnung, Fehler, Wichtig).

    Beispiel:

    .. hint::

    Hier wird ein Hinweis ausgegeben.

    Ergebnis:

    Hinweis

    Hier wird ein Hinweis ausgegeben.

    Neben den oben genannten Direktiven kann auch eine topic-Umgebung genutzt werden, um eine beliebig benannte Infobox erzeugen. Dabei wird in der gleichen Zeile de im Anschluss an .. topic:: der Name der Box geschrieben.

  • math

    Mit der math-Direktive können mathematische Formeln, geschrieben als LaTeX-Code, als eigenständige zentrierte Zeilen in das Dokument eingebunden werden.

    Beispiel:

    .. math::

    a^2 + b^2 = c^2

    Ergebnis:

    a^2 + b^2 = c^2

    Die math-Direktive bietet zusätzlich die Option, der angegebenen Formel eine Sprungmarke („Label“) und eine automatisch vergebene Nummer zu vergeben. Hierzu wird eine eigene Zeile der Form :label: Name-des-Labels unmittelbar als erste Zeile der math-Direktive eingefügt (mit gleicher Einrückung wie die eigentliche Formel).

    Beispiel:

    .. math::
    :label: einstein-und-pythagoras

    E \underset{Einstein}{=} m \cdot c^2
    \underset{Pythagoras}{=} m \cdot (a^2 + b^2)

    Ergebnis:

    (1)E \underset{Einstein}{=} m \cdot c^2 \underset{Pythagoras}{=} m \cdot (a^2 + b^2)

    Auf die Formel kann dann mittels der Referenz eqr:`Name-des-Labels` an einer beliebigen anderen Stelle des Dokuments (derzeit jedoch nur innerhalb einer einzelnen Quellcode-Datei) verwiesen werden.

  • code-block

    Die code-block-Direktive ermöglicht es, wie der Name bereits andeutet, Quellcode-Beispiele in das Dokument einzufügen. Dabei kann in der gleichen Zeile im Anschluss an .. code-block:: eine Codesprache aus dieser Liste ausgewählt werden, um ein Syntax-Highlighting zu aktivieren.

    Beispiel:

    .. code-block:: sh
    :linenos:

    # Show the local network address
    # Result: Something like 192.168.1.105
    hostname -I | cut -d' ' -f1

    Ergebnis:

    1
2
3
    # Show the local network address
# Result: Something like 192.168.1.105
hostname -I | cut -d' ' -f1

Quellcode wird üblicherweise in Maschinenschrift ausgegeben; jegliches Inline-Markup wird dabei ignoriert. Möchte man Inline-Markup (Roles) dennoch interpretiert haben, um beispielsweise Verlinkungen innerhalb des Quellcodes zu setzen, kann anstelle von code-block die parsed-literal-Direktive verwendet werden, die ansonsten die gleiche Syntax aufweist.

Weitere Gestaltungsmöglichkeiten von Absätzen sind in der Liste aller RST-Direktiven (en.) aufgeführt.

Aufzählungen und Beschreibungen

In RestructuredText sind sowohl nummerierte wie auch nicht nummerierte Aufzählungen möglich. Die Syntax hierfür ist sehr simpel:

*Beispiel einer nummerierten Liste:*

1. Dies hier ist ein Blindtext zum Testen von Textausgaben. Wer diesen Text
   liest, ist selbst schuld. Der Text gibt lediglich den Grauwert der
   Schrift an.
2. | Dies hier ist ein Blindtext zum Testen von Textausgaben.
   | Wer diesen Text liest, ist selbst schuld.
   | Der Text gibt lediglich den Grauwert der Schrift an.

*Beispiel einer nicht nummerierten Liste:*

* Dies hier ist ein Blindtext zum Testen von Textausgaben. Wer diesen Text
  liest, ist selbst schuld. Der Text gibt lediglich den Grauwert der
  Schrift an.
* | Dies hier ist ein Blindtext zum Testen von Textausgaben.
  | Wer diesen Text liest, ist selbst schuld.
  | Der Text gibt lediglich den Grauwert der Schrift an.

Ergebnis:

Beispiel einer nummerierten Liste:

  1. Dies hier ist ein Blindtext zum Testen von Textausgaben. Wer diesen Text liest, ist selbst schuld. Der Text gibt lediglich den Grauwert der Schrift an.

  2. Dies hier ist ein Blindtext zum Testen von Textausgaben.
    Wer diesen Text liest, ist selbst schuld.
    Der Text gibt lediglich den Grauwert der Schrift an.

Beispiel einer nicht nummerierten Liste:

  • Dies hier ist ein Blindtext zum Testen von Textausgaben. Wer diesen Text liest, ist selbst schuld. Der Text gibt lediglich den Grauwert der Schrift an.

  • Dies hier ist ein Blindtext zum Testen von Textausgaben.
    Wer diesen Text liest, ist selbst schuld.
    Der Text gibt lediglich den Grauwert der Schrift an.

Für nicht nummerierte Aufzählungen können anstelle des Zeichens * auch die Zeichen - oder + verwendet werden; in der Ausgabe werden die Aufzählungszeichen unabhängig davon anhand der Aufzählungstiefe ausgewählt (innerhalb einer Aufzählung sind auch weitere Aufzählungen möglich).

Beim Erstellen von Aufzählungen muss lediglich darauf geachtet werden, dass vor und nach der Aufzählung im Quellcode eine leere Zeile steht und die einzelnen Einträge gleich weit eingerückt sind. Die einzelnen Einträge werden, sofern sie nicht in eine Zeile passen, automatisch am Seitenrand umgebrochen; manuelle Umbrücke können erzwungen werden, indem zu Beginn jeder neu zu erstellenden Zeile ein |-Zeichen eingegeben wird. Auch hierbei muss auf eine gleiche Einrückungstiefe der Textzeilen geachtet werden.

Automatisch nummerierte Aufzählungen können mittels #. als Aufzählungszeichen erstellt werden; in diesem Fall sind zwischen den einzelnen Einträgen allerdings keine RestructuredText-Elemente erlaubt, die ohne Einrückung zu Beginn der Zeile eingegeben werden müssen (beispielsweise Sprungmarken); in diesem Fall fängt die folgende Aufzählung nämlich wieder mit 1. an.

Bei Beschreibungen verwendet man das zu beschreibende Wort als „Aufzählungszeichen“. Die Syntax hierzu ist folgende:

**Wort1:**
    Beschreibung zu Wort1.

**Wort2:**
    Beschreibung zu Wort2.

Ergebnis:

Wort1:
Beschreibung zu Wort1.
Wort2:
Beschreibung zu Wort2.

Auch bei den Beschreibungen muss nur auf die einheitliche Einrückung des Beschreibungs-Textes geachtet werden; der Text kann dann auch aus mehreren Absätzen bestehen.

Sprungmarken und Referenzen

Ein sehr nützliche von Wiki-Seiten besteht darin, mittels eines klickbaren Links auf eine andere Stelle in der Dokumentation oder auf eine externe Seite verweisen zu können. RestructuredText bietet dazu folgende Möglichkeiten:

  • Mittels `Link-Bezeichnung <Adresse>`_ kann ein mit einer bestimmten Bezeichnung versehener Link auf eine externe Seite gesetzt werden. Soll eine Adresse ohne eigene Bezeichnung verlinkt werden, so genügt es die Adresse ohne weitere Syntax anzugeben, beispielsweise https://www.grund-wissen.de für https://www.grund-wissen.de ; ein Link wird dabei automatisch erzeugt.

  • Mittels einer eigenen Zeile der Form .. _Name der Sprungmarke: und einer darauf folgenden Leerzeile kann an einer beliebigen Stelle innerhalb der Dokumentation eine Sprungmarke (auch „Label“ oder „Anker“ genannt) festgelegt werden. Auf diese Sprungmarke kann dann von einer beliebigen anderen Stelle im Dokument aus mittels :ref:`Link-Bezeichnung <Name der Sprungmarke>` verwiesen werden.

    Diese Methode funktioniert auch, wenn sich die Sprungmarke und die Referenz in verschiedenen Dateien des Quelltextes einer Dokumentation befinden.

  • Mittels der „Intersphinx“-Erweiterung, die beim Sphinx-Quickstart ausgewählt werden kann[3], ist es möglich, auch auf Sprungmarken anderer Sphinx-Projekte zu verweisen. Hierzu muss die Konfigurationsdatei conf.py um einen oder mehrere Einträge mit folgender Form ergänzt werden:

    intersphinx_mapping = {
    'sphinx': ('http://sphinx-doc.org', None),
    'gw': ('http://grund-wissen.de', None)
}

    Damit kann beispielsweise mittels :ref:`Inhaltsverzeichnis der Sphinx-Dokumentation <sphinx:contents>` ein Link auf das Inhaltsverzeichnis der Sphinx-Dokumentation gesetzt werden, das eine Sprungmarke namens contents enthält (dies zeigt ein Blick in den Quelltext der Seite, der üblicherweise in der Seitenleiste verlinkt ist). Führt man den Mauszeiger über einen solchen Link, so werden der Name und die Versionsnummer der jeweiligen Dokumentation eingeblendet.

Fußnoten, Zitierungen und Index-Einträge

In RestructuredText gibt es die Möglichkeit, ergänzende Anmerkungen als Fußnoten aus dem normalen Text „auszulagern“. Hierzu wird im Haupttext eine Marke der Form [#]_ oder [#Name]_ gesetzt, d.h. ein Rautenzeichen in eckigen Klammern, gefolgt von einem Unterstrich.[4] Optional kann jeder Marke einer Fußnote im Anschluss an die Nummer oder das Rautensymbol (Autonummerierung) noch ein Name hinzugefügt werden, um im Quelltext die Zuordnung der Fußnoten-Marke zur Fußnote zu erleichtern.

An einer späteren Stelle innerhalb der gleichen Datei, meist am Ende, wird der Inhalt der jeweiligen Fußnote dann absatzweise mittels .. [#] Inhalt beziehungsweise .. [#Name] Inhalt angegeben, wobei [#Name] der Marke im Haupttext entsprechen muss.

Beispiel:

Etwas Text. [#FN1]_

Weiterer Text.

...


.. [#FN1] Eine Anmerkung als Fußnote.

Ergebnis:

Etwas Text.[1]


Weiterer Text.


...






[1]Eine Anmerkung als Fußnote.

Erstreckt sich der Inhalt einer Fußnote über mehrere Zeilen, so muss jede Zeile nach der ersten um mindestens ein Leerzeichen eingerückt werden (üblicherweise werden Folgezeilen eine Tabulatorbreite weit eingerückt, um eine bessere Lesbarkeit zu erzielen).

Zitierungen und Literaturverzeichnis

Innerhalb einer Dokumentation sind auch Verweise auf literarische Werke anderer Autoren möglich. Für jedes zitierte Werk wird dabei ein Kurzname vergeben, häufig in der Form AutorJahr. Im Haupttext (oder in einer Fußzeile) kann auf diese Weise mittels [Kurzname]_ auf eine genauere Umschreibung der Literaturquelle verwiesen werden, die einmalig an einer beliebigen Stelle der Dokumentation mittels eines Eintrags der Form .. [Kurzname] Informationen erfolgt.[5]

In der HTML-Version werden alle Literatur-Einträge an genau der Stelle eingefügt, an der sie gesetzt werden. Insofern empfiehlt sich eine eigene Datei namens quellen.rst (oder ähnlich), in der die Literaturhinweise und Quellenangaben gesammelt aufgelistet sind. In der LaTeX-Version wird am Ende des Dokuments automatisch ein Literaturverzeichnis angelegt.

Index-Einträge

Innerhalb der Dokumentation können an beliebiger Stelle mittels folgender Syntax Einträge für ein Stichwortverzeichnis festgelegt werden:

.. index:: Bezeichnung

In der HTML-Version wird ein Link auf die Index-Seite üblicherweise auf der rechten Seite am oberen und unteren Seitenrand eingeblendet. In der LaTeX-Version wird das Stichwortverzeichnis auf den letzten Seiten der Dokumentation abgedruckt. Eine Verlinkung mit den entsprechenden Textstellen (in der Druckversion mitsamt Angabe der jeweiligen Seitennummer) erfolgt automatisch.

  • Um mehrere Index-Einträge zur gleichen Textstelle zu erreichen, können die Bezeichnungen der gewünschten Einträge, durch Kommas voneinander getrennt, in einer einzigen Zeile aufgelistet werden:

    .. index:: Eintrag1, Eintrag2

  • Werden zwei Einträge durch einen Strichpunkt getrennt, so wird der zweite Eintrag als „Unterkategorie“ des ersten im Stichwortverzeichnis angezeigt:

    .. index:: Eintrag; Unterkategorie

Eine ausführliche Beschreibung findet sich in der Sphinx-Dokumentaion.

Bilder und Tabellen

Bilder können in Restructured-Text entweder mittels einer image- oder mittels einer figure-Direktive eingebunden werden; letztere muss verwendet werden, wenn die Abbildung eine Bildunterschrift („Caption“) erhalten soll.

Die Syntax für den Einbau eines Bildes sieht etwa folgendermaßen aus:

.. figure:: ../pics/no-littering.png
    :name: fig-beispiel-bild
    :alt:  fig-beispiel-bild
    :align: center
    :width: 20%

    Beispiel-Bild "No littering" ohne weitere Beschreibung.

    .. only:: html

        :download:`SVG: Beispiel-Bild ("No littering") <../pics/no-littering.svg>`

Ergebnis:

fig-beispiel-bild

Beispiel-Bild „No littering“ ohne weitere Beschreibung.

SVG: Beispiel-Bild ("No littering")

Bei Verwendung der figure-Direktive wird zunächst der Pfad der einzubindenden Graphik angegeben. Die :name:-Attribut angegebene Bezeichnung kann in Referenzen als Label aufgegriffen werden; die als :alt:-Attribut angegebene Bezeichnung wird im Webbrowser während des Ladens der Graphik oder im Fall einer nicht auffindbaren Graphik-Datei angezeigt.

Über das Attribut :align: wird die Ausrichtung der Graphik am Text als left, center oder right festgelegt. Die Angabe der Breite kann über das :width:-Attribut entweder als feste Längeneinheit (beispielsweise 4.2 cm) oder relativ zur Textbreite als Prozentangabe erfolgen. Als Alternative zur Angabe einer Breite kann die Größe einer Abbildung auch mittels einer :height:- oder scale-Angabe (in Prozent der Original-Bildgröße) festgelegt werden. Bei der Angabe einer Bildunterschrift innerhalb einer figure-Umgebung muss wiederum auf die richtige Einrücktiefe geachtet werden.

Bei der image-Direktive können, abgesehen von der Bildunterschrift, ebenfalls die oben genannten Attribute angegeben werden; dafür kann (nur) bei der image-Direktive als zusätzliches Argument mittels :target: eine Zieladresse angeegben werden, auf die beim Anklicken des Bildes verlinkt wird.

Zur Eingabe von Tabellen gibt es in RestructuredText ebenfalls mehrere Möglichkeiten:

  • Bei einer „Gitter-Tabelle“ wird die tabellarische Anordnung bereits im Quellcode angedeutet:

    +------------------+---------------+---------------+
| Art der Einträge | Eigenschaft 1 | Eigenschaft 2 |
+==================+===============+===============+
| Gegenstand 1     | eckig         | rot           |
+------------------+---------------+---------------+
| Gegenstand 2     | rund          | blau          |
+------------------+---------------+---------------+

    Ergebnis:

    Art der Einträge Eigenschaft 1 Eigenschaft 2
    Gegenstand 1 eckig rot
    Gegenstand 2 rund blau

    Werden beim ersten „Querstrich“ in der Tabelle anstelle der =-Zeichen --Zeichen gesetzt, so wird die erste Zeile in normaler Schrift (nicht fettgedruckt) ausgegeben.

    Tabellen gemäß dieser Syntax sind mühsam, sofern der Texteditor nicht ein geeignetes Feature dafür mitbringt (für den Editor Vim gibt es hierfür beispielsweise das Table-Mode-Plugin). Der Vorteil solcher Tabellen liegt vor allem in der angenehmen Lesbarkeit im Quellcode.

    Nicht geeignet sind Grid-Tabellen, wenn auch Links oder mathematische Formeln in der Tabelle vorkommen sollen. Diese machen im Quellcode mehr Buchstaben aus als in der Ausgabe, so dass die Spalten dadurch breiter als nötig gedruckt werden. Hierfür sollte eher „List-Tables“ verwendet werden.

  • Bei „List Tables“ werden die Einträge einer Tabelle in Form einer verschachtelten Aufzählung angegeben. Die Syntax hierzu sieht etwa folgendermaßen aus:

    .. list-table::
    :name: tab-beispieltabelle
    :widths: 50 50 50
    :header-rows: 0

    * - Art der Einträge
      - Eigenschaft 1
      - Eigenschaft 2
    * - Gegenstand 1
      - eckig
      - rot
    * - Gegenstand 2
      - rund
      - blau

    Ergebnis:

    Art der Einträge Eigenschaft 1 Eigenschaft 2
    Gegenstand 1 eckig rot
    Gegenstand 2 rund blau

    Soll die erste Zeile der Tabelle fett gedruckt ausgegeben werden, muss das Attribut :header-rows auf 1 gesetzt werden.

    Der Vorteil von List-Tables liegt darin, dass in den einzelnen Einträgen beliebige Inline-Direktiven verwendet werden können (Links, Formeln, usw). Ebenso kann die „Gewichtung“ der einzelnen Spaltenbreiten durch die Angabe der :widths:-Werte manuell angepasst werden. Im obigen Beispiel werden die drei Spalten der Tabelle in einem Breitenverhältnis von 50:50:50, also mit gleicher Breite ausgegeben.

    Wird in der gleichen Zeile direkt hinter .. list-table:: ein Titel angegeben, so wird dieser als Überschrift über die Tabelle gedruckt.

  • Mit einer „CSV-Table“ kann der Inhalt der Tabelle durch „Comma Seperated Values“ erfolgen. Diese Einträgte können wahlweise im Block der Listen-Direktive oder in einer separaten .csv-Datei angegeben werden. Das obige Beispiel kann damit etwa folgendermaßen aussehen:

    .. csv-table::
    :widths: 50 50 50

    Art der Einträge , Eigenschaft 1 , Eigenschaft 2
    Gegenstand 1 , eckig , rot
    Gegenstand 2 , rund , blau

    Ergebnis:

    Art der Einträge Eigenschaft 1 Eigenschaft 2
    Gegenstand 1 eckig rot
    Gegenstand 2 rund blau

    Soll anstelle von , ein anderes Zeichen zur Trennung der einzelnen Einträge verwendet werden, so kann dieses mittels des :delim:-Attributs angegeben werden.

    Anstelle einer direkten Eingabe der Tabelle kann auch der Inhalt einer externen .csv-Datei verwendet werden; hierzu muss entweder ein Pfad als :file:-Attribut oder eine Web-Adresse als :url:-Attribut angegeben werden.

Substitutionen

Mittels Substitutionen kann innerhalb eines Absatzes ein Text-Label durch einen zugehörigen anderen Inhalt ersetzt werden. Dies ist insbesondere hilfreich, um kleine Graphiken wie Icons in den Fließtext einzubinden; dies ist insbesondere bei der Dokumentation von Programmen mit graphischen Bedienoberflächen nützlich.

Die Syntax hierfür lautet etwa folgendermaßen:

Beispiel:

.. Variante 1: Text-Hervorherbung und Ersetzung

Blindtext |hallo-welt| Blindtext

.. Variante 2: Einbau einer Icon-Graphik

Blindtext |symbol| Blindtext


.. |hallo-welt| replace:: **Hallo Welt!**

.. |symbol| image:: pics/symbol-amperemeter-klein.png
                .. alt: Amperemeter-Symbol

Ergebnis:

Blindtext Hallo Welt! Blindtext

Blindtext symbol Blindtext

Substitution können also, wie das obige Beispiel zeigt, weitgehend ähnlich wie Fußnoten verwendet werden, mit dem wesentlichen Unterschied, dass |-Symbole anstelle der eckigen Klammern gesetzt werden müssen.

Links

Anmerkungen:

[1]

Eine „Direktive“ ist ein Syntax-Element, das Auswirkung auf einen ganzen Absatz hat, also auf einen Bereich, der durch zwei leere Zeilen begrenzt wird. Im kürzesten Fall, wie bei der .. rubric::-Direktive, besteht der Absatz aus einer einzelnen Zeile, die unmittelbar hinter dem Namen der Direktive angegeben wird.

Eine Direktive wird allgemein durch zwei Punkte und ein Leerzeichen zu Beginn einer Zeile eingeleitet, gefolgt vom Namen der Direktive, zwei Doppelpunkten und einem Leerzeichen: .. name:: . Vor und nach einer Direktive muss (mindestens) eine Leerzeile eingefügt werden.

Je nach Art der Direktive kann hinter ihrem Namen eine weitere Bezeichnung und/oder eine beliebige Anzahl von Absätzen folgen. Um den Wirkungsbereich der Direktive kenntlich zu machen, werden die Absätze dabei eine Tabulatorbreite weit eingerückt (üblicherweise 4 Leerzeichen).

Siehe auch Liste aller RST-Direktiven (en.).
[2]

Eine „Role“ ist ein Syntax-Element, das Auswirkung auf eine Textstelle innerhalb eines Absatzes hat, d.h. auf einen Bereich, der durch zwei Leerzeichen begrenzt wird („Inline-Markup“).

Eine Role hat im allgemeinen folgende Struktur: :name:`Inhalt`. Die einzigen Ausnahmen bilden die drei oben genannten (wohl am häufigsten auftretenden) Roles für kursiven und fettgedruckten Text sowie Text in Maschinenschrift. Sie stellen praktisch nutzbare Abkürzungen für :emphasis:`Text`, :strong:`Text` sowie :literal:`Text` dar, um Tippbarbeit zu sparen und den Quelltext lesbarer zu gestalten.

Siehe auch Liste aller RST-Roles (en.).
[3]Die Intersphinx-Erweiterung lässt sich ebenso nutzen, wenn in der Konfigurationsdatei conf.py die extension-Liste um den Eintrag 'sphinx.ext.intersphinx' ergänzt wird.
[4]

Optional können die Nummern der Fußnoten auch in der Art [01]_, [02]_ beziehungsweise [01Name]_, [02Name]_ usw. selbst vergeben werden. Davon ist allerdings abzuraten, denn sollte zu einem späteren Zeitpunkt an einer Stelle mitten im Text eine weitere Fußnote eingefügt werden, so müssen die Nummern aller folgenden Fußnoten manuell angepasst werden. Durch automatisch nummerierte Fußnoten bleibt einem diese Arbeit sicher erspart.

Tip: Durch die Option trim_footnote_reference_space = True in der conf.py wird ein mögliches Leerzeichen vor Fußnoten, wie in deutschsprachiger Literatur üblich, ignoriert.
[5]

Die Syntax von Zitierungen ähnelt somit der Syntax von Fußnoten, mit dem Unterschied, dass innerhalb der eckigen Klammern keine Nummer beziehungsweise kein einleitendes Raute-Zeichen auftritt.

Jede Literaturangabe sollte folgende Informationen beinhalten: Name des Autors beziehungsweise der Autoren, Titel des Werks, (gegebenenfalls) Name des Verlags, Erscheinungsjahr.