Rollen

Sphinx verwendet interpretierte Textrollen, um semantisches Markup in Dokumente einzufügen. Sie werden wie folgt geschrieben: :rolename:`Inhalt`.

Hinweis

Die Standardrolle (`Inhalt`) hat standardmäßig keine besondere Bedeutung. Sie können sie für alles verwenden, was Sie möchten, z. B. für Variablennamen. Verwenden Sie den Konfigurationswert default_role, um ihn auf eine bekannte Rolle zu setzen. Die Rolle any, um alles zu finden, oder die Rolle py:obj, um Python-Objekte zu finden, sind dafür sehr nützlich.

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

Querverweise

Siehe Querverweise.

Querverweisrollen umfassen

Inline-Code-Hervorhebung

:code:

Ein Inline-Codebeispiel. Wenn diese Rolle direkt verwendet wird, zeigt sie den Text nur ohne Syntaxhervorhebung als Literal an.

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

Anzeige: Standardmäßig werden Inline-Codes wie 1 + 2 ohne Hervorhebung angezeigt.

Im Gegensatz zur Direktive code-block berücksichtigt diese Rolle nicht die Standardsprache, die von der highlight-Direktive festgelegt wird.

Um Syntaxhervorhebung zu aktivieren, müssen Sie zuerst die Docutils role-Direktive verwenden, um eine benutzerdefinierte Rolle für eine bestimmte Sprache zu definieren.

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

Um ein mehrzeiliges Codebeispiel anzuzeigen, verwenden Sie stattdessen die Direktive code-block.

Mathematik

:math:

Rolle für Inline-Mathematik. Verwenden Sie sie so:

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

Anzeige: Seit Pythagoras wissen wir, dass \(a^2 + b^2 = c^2\).

:eq:

Dasselbe wie math:numref.

Anderes semantisches Markup

Die folgenden Rollen tun nichts Besonderes, außer den Text in einem anderen Stil zu formatieren.

:abbr:

Eine Abkürzung. Wenn der Rolleninhalt eine Erklärung in Klammern enthält, wird diese speziell behandelt: Sie wird in einem Tooltip in HTML angezeigt und in LaTeX nur einmal ausgegeben.

Zum Beispiel: :abbr:`LIFO (Last-In, First-Out)` wird als LIFO angezeigt.

Hinzugefügt in Version 0.6.

:command:

Der Name eines OS-Befehls, z. B. rm.

Zum Beispiel: rm

:dfn:

Markieren Sie die definierende Instanz eines Begriffs im Text. (Es werden keine Indexeinträge generiert.)

Zum Beispiel: Binärmodus

:file:

Der Name einer Datei oder eines Verzeichnisses. Innerhalb des Inhalts können Sie geschweifte Klammern verwenden, um einen „variablen“ Teil anzuzeigen, z. B.

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

Anzeige: ... ist installiert in /usr/lib/python3.x/site-packages ...

In der erstellten Dokumentation wird das x anders angezeigt, um zu signalisieren, dass es durch die kleinere Python-Version ersetzt werden soll.

:guilabel:

Beschriftungen, die als Teil einer interaktiven Benutzeroberfläche dargestellt werden, sollten mit guilabel markiert werden. Dies schließt Beschriftungen von textbasierten Schnittstellen ein, wie sie z. B. mit curses oder anderen textbasierten Bibliotheken erstellt werden. Jede Beschriftung, die in der Schnittstelle verwendet wird, sollte mit dieser Rolle markiert werden, einschließlich Schaltflächenbeschriftungen, Fenstertiteln, Feldnamen, Menü- und Menüauswahlbezeichnungen und sogar Werte in Auswahllisten.

Geändert in Version 1.0: Eine Beschleunigertaste für die GUI-Beschriftung kann mit einem Ampersand eingeschlossen werden; dies wird aus der Ausgabe entfernt und unterstrichen angezeigt (z. B.: :guilabel:`&Abbrechen` zeigt Abbrechen). Um ein wörtliches Ampersand einzufügen, verdoppeln Sie es.

:kbd:

Eine Abfolge von Tastendrücken markieren. Welche Form die Tastensequenz annimmt, kann von plattform- oder anwendungsspezifischen Konventionen abhängen. Wenn keine relevanten Konventionen vorhanden sind, sollten die Namen von Modifikatortasten ausgeschrieben werden, um die Zugänglichkeit für neue Benutzer und Nicht-Muttersprachler zu verbessern. Zum Beispiel kann eine xemacs-Tastensequenz wie :kbd:`C-x C-f` markiert werden, aber ohne Bezugnahme auf eine bestimmte Anwendung oder Plattform sollte dieselbe Sequenz als :kbd:`Control-x Control-f` markiert werden, was entsprechend C-x C-f und Control-x Control-f angezeigt wird.

:mailheader:

Der Name eines Mail-Headers im Stil von RFC 822. Dieses Markup impliziert nicht, dass der Header in einer E-Mail-Nachricht verwendet wird, kann aber verwendet werden, um auf jeden Header des gleichen „Stils“ zu verweisen. Dies wird auch für Header verwendet, die durch die verschiedenen MIME-Spezifikationen definiert sind. Der Header-Name sollte so eingegeben werden, wie er üblicherweise in der Praxis vorkommt, wobei die Kamelschreibweise bevorzugt wird, wenn mehr als eine gebräuchliche Verwendung existiert. Zum Beispiel: :mailheader:`Content-Type` wird als Content-Type angezeigt.

:makevar:

Der Name einer make-Variable.

Zum Beispiel: help

:manpage:

Ein Verweis auf eine Unix-Handbuchseite, einschließlich der Sektion, z. B. :manpage:`ls(1)` zeigt ls(1) an. Erzeugt einen Hyperlink zu einer externen Seite, die die Handbuchseite rendert, wenn manpages_url definiert ist.

Geändert in Version 7.3: Ermöglicht die Angabe eines Ziels mit <>, ähnlich wie bei Hyperlinks. Zum Beispiel zeigt :manpage:`blah <ls(1)>` blah an.

:menuselection:

Menüauswahlen sollten mit der Rolle menuselection markiert werden. Dies wird verwendet, um eine vollständige Sequenz von Menüauswahlen zu markieren, einschließlich der Auswahl von Untermenüs und der Wahl einer bestimmten Operation, oder einer beliebigen Teilsequenz einer solchen Sequenz. Die Namen der einzelnen Auswahlen sollten durch --> getrennt werden.

Zum Beispiel, um die Auswahl „Start > Programme“ zu markieren, verwenden Sie dieses Markup:

:menuselection:`Start --> Programs`

Anzeige: Start ‣ Programme

Wenn eine Auswahl mit einem nachfolgenden Indikator eingeschlossen wird, wie z. B. die Auslassungspunkte, die einige Betriebssysteme verwenden, um anzuzeigen, dass der Befehl ein Dialogfeld öffnet, sollte der Indikator vom Auswahlnamen weggelassen werden.

menuselection unterstützt auch Ampersand-Beschleuniger, genau wie guilabel.

:mimetype:

Der Name eines MIME-Typs oder eine Komponente eines MIME-Typs (der Haupt- oder Nebenteil, einzeln genommen).

Zum Beispiel: text/plain

:newsgroup:

Der Name einer Usenet-Newsgruppe.

Zum Beispiel: comp.lang.python

:program:

Der Name eines ausführbaren Programms. Dies kann je nach Plattform vom Dateinamen des ausführbaren Programms abweichen. Insbesondere sollte die .exe (oder eine andere) Erweiterung bei Windows-Programmen weggelassen werden.

Zum Beispiel: curl

:regexp:

Ein regulärer Ausdruck. Anführungszeichen sollten nicht enthalten sein.

Zum Beispiel: ([abc])+

:samp:

Ein Stück literaler Text, wie z. B. Code. Innerhalb des Inhalts können Sie geschweifte Klammern verwenden, um einen „variablen“ Teil anzuzeigen, wie bei file. Zum Beispiel wird in :samp:`print(1+{variable})` der Teil variable hervorgehoben: print(1+variable)

Wenn Sie die Anzeige des „variablen Teils“ nicht benötigen, verwenden Sie stattdessen die Standardrolle code.

Geändert in Version 1.8: Es ist nun möglich, geschweifte Klammern mit doppeltem Backslash zu escapen. Zum Beispiel wird in :samp:`print(f"answer=\\{1+{variable}*2\\}")` der Teil variable hervorgehoben und die escapeten geschweiften Klammern werden angezeigt: print(f"answer={1+variable*2}")

Es gibt auch eine index-Rolle zur Generierung von Indexeinträgen.

Die folgenden Rollen generieren externe Links

:cve:

Ein Verweis auf einen Common Vulnerabilities and Exposures-Datensatz. Dies generiert entsprechende Indexeinträge. Der Text „CVE Nummer“ wird generiert; mit einem Link zu einer Online-Kopie der angegebenen CVE. Sie können zu einem bestimmten Abschnitt verlinken, indem Sie :cve:`Nummer#Anker` verwenden.

Zum Beispiel: CVE 2020-10735

Hinzugefügt in Version 8.1.

:cwe:

Ein Verweis auf eine Common Weakness Enumeration. Dies generiert entsprechende Indexeinträge. Der Text „CWE Nummer“ wird generiert; in der HTML-Ausgabe mit einem Link zu einer Online-Kopie der angegebenen CWE. Sie können zu einem bestimmten Abschnitt verlinken, indem Sie :cwe:`Nummer#Anker` verwenden.

Zum Beispiel: CWE 787

Hinzugefügt in Version 8.1.

:pep:

Ein Verweis auf ein Python Enhancement Proposal. Dies generiert entsprechende Indexeinträge. Der Text „PEP Nummer“ wird generiert; in der HTML-Ausgabe ist dieser Text ein Hyperlink zu einer Online-Kopie des angegebenen PEP. Sie können zu einem bestimmten Abschnitt verlinken, indem Sie :pep:`Nummer#Anker` sagen.

Zum Beispiel: PEP 8

:rfc:

Ein Verweis auf einen Internet Request for Comments. Dies generiert entsprechende Indexeinträge. Der Text „RFC Nummer“ wird generiert; in der HTML-Ausgabe ist dieser Text ein Hyperlink zu einer Online-Kopie des angegebenen RFC. Sie können zu einem bestimmten Abschnitt verlinken, indem Sie :rfc:`Nummer#Anker` sagen.

Zum Beispiel: RFC 2324

Beachten Sie, dass es keine speziellen Rollen für das Einfügen von Hyperlinks gibt, da Sie für diesen Zweck die standardmäßige reStructuredText-Auszeichnung verwenden können.

Substitutionen

Das Dokumentationssystem bietet einige Substitutionen, die standardmäßig definiert sind. Sie werden in der Build-Konfigurationsdatei festgelegt.

|release|

Ersetzt durch die Projektversion, auf die sich die Dokumentation bezieht. Dies soll die vollständige Versionszeichenkette einschließlich Alpha/Beta/Release-Kandidaten-Tags sein, z. B. 2.5.2b3. Festgelegt durch release.

|version|

Ersetzt durch die Projektversion, auf die sich die Dokumentation bezieht. Dies soll nur die Haupt- und Nebenversionsanteile enthalten, z. B. 2.5, auch für die Version 2.5.1. Festgelegt durch version.

|today|

Ersetzt durch entweder das heutige Datum (das Datum, an dem das Dokument gelesen wird) oder das im Build-Konfigurationsfile festgelegte Datum. Hat normalerweise das Format 14. April 2007. Festgelegt durch today_fmt und today.

|translation progress|

Ersetzt durch den Übersetzungsfortschritt des Dokuments. Diese Substitution ist für Dokumentenübersetzer als Marker für den Übersetzungsfortschritt des Dokuments gedacht.