Docutils-Markup-API¶

Dieser Abschnitt beschreibt die API zum Hinzufügen von reStructuredText-Markup-Elementen (Rollen und Direktiven).

Rollen¶

Rollen folgen der unten beschriebenen Schnittstelle. Sie müssen von einer Erweiterung mit Sphinx.add_role() oder Sphinx.add_role_to_domain() registriert werden.

def role_function(
    role_name: str, raw_source: str, text: str,
    lineno: int, inliner: Inliner,
    options: dict = {}, content: list = [],
) -> tuple[list[Node], list[system_message]]:
    elements = []
    messages = []
    return elements, messages

Die Parameter options und content werden nur für benutzerdefinierte Rollen verwendet, die über die role-Direktive erstellt wurden. Der Rückgabewert ist ein Tupel aus zwei Listen, die erste enthält die Textknoten und Elemente der Rolle, und die zweite enthält alle generierten Systemmeldungen. Weitere Informationen finden Sie in der Übersicht zu benutzerdefinierten Rollen von Docutils.

Erstellen benutzerdefinierter Rollen¶

Sphinx bietet zwei Basisklassen für die Erstellung benutzerdefinierter Rollen: SphinxRole und ReferenceRole.

Diese stellen eine klassenbasierte Schnittstelle zur Erstellung von Rollen bereit, wobei die Hauptlogik in Ihrer run()-Methode implementiert werden muss. Die Klassen bieten eine Reihe nützlicher Methoden und Attribute wie self.text, self.config und self.env. Die Klasse ReferenceRole implementiert die Logik title <target> von Sphinx und stellt die Attribute self.target und self.title zur Verfügung. Dies ist nützlich für die Erstellung von Querverweis-Rollen.

Direktiven¶

Direktiven werden von Klassen verarbeitet, die von docutils.parsers.rst.Directive abgeleitet sind. Sie müssen von einer Erweiterung mit Sphinx.add_directive() oder Sphinx.add_directive_to_domain() registriert werden.

class docutils.parsers.rst.Directive[Quelle]¶

Die Markup-Syntax der neuen Direktive wird durch die folgenden fünf Klassenattribute bestimmt

required_arguments = 0¶: Anzahl der erforderlichen Direktivenargumente.

optional_arguments = 0¶: Anzahl der optionalen Argumente nach den erforderlichen Argumenten.

final_argument_whitespace = False¶: Darf das letzte Argument Leerzeichen enthalten?

option_spec = None¶

Zuordnung von Optionsnamen zu Validierungsfunktionen.

Optionsvalidierungsfunktionen nehmen einen einzelnen Parameter entgegen, das Optionsargument (oder None, wenn nicht angegeben), und sollten es validieren oder in die richtige Form konvertieren. Sie lösen ValueError oder TypeError aus, um einen Fehler anzuzeigen.

Es gibt mehrere vordefinierte und möglicherweise nützliche Validatoren im Modul docutils.parsers.rst.directives.

has_content = False¶: Darf die Direktive Inhalt haben?

Neue Direktiven müssen die Methode run() implementieren

run()[Quelle]¶: Diese Methode muss die Direktivenargumente, Optionen und den Inhalt verarbeiten und eine Liste von Docutils/Sphinx-Knoten zurückgeben, die an der Stelle, an der die Direktive angetroffen wurde, in den Dokumentenbaum eingefügt werden.

Instanzattribute, die auf der Direktive immer gesetzt sind

name¶: Der Name der Direktive (nützlich, wenn dieselbe Direktivenklasse unter mehreren Namen registriert wird).

arguments¶: Die der Direktive übergebenen Argumente als Liste.

options¶: Die der Direktive übergebenen Optionen als Wörterbuch, das Optionsnamen mit validierten/konvertierten Werten abbildet.

content¶: Der Direktiveninhalt, falls angegeben, als ViewList.

lineno¶: Die absolute Zeilennummer, an der die Direktive erschien. Dies ist nicht immer ein nützlicher Wert; verwenden Sie stattdessen srcline.

content_offset¶: Interner Offset des Direktiveninhalts. Wird beim Aufruf von nested_parse (siehe unten) verwendet.

block_text¶: Der String, der die gesamte Direktive enthält.

state¶
state_machine¶: Der Status und die Zustandsmaschine, die die Analyse steuern. Wird für nested_parse verwendet.

Siehe auch

HOWTO zur Erstellung von Direktiven in der Docutils-Dokumentation

Parsen von Direktiven-Inhalt als reStructuredText¶

Viele Direktiven enthalten mehr Markup, das analysiert werden muss. Verwenden Sie hierfür eine der folgenden APIs aus der Methode run()

Die erste Methode analysiert den gesamten Inhalt der Direktive als Markup, während die zweite nur den angegebenen Text-String analysiert. Beide Methoden geben die analysierten Docutils-Knoten in einer Liste zurück.

Die Methoden werden wie folgt verwendet

def run(self) -> list[Node]:
    # either
    parsed = self.parse_content_to_nodes()
    # or
    parsed = self.parse_text_to_nodes('spam spam spam')
    return parsed

Hinweis

Die obigen Hilfsmethoden wurden in Sphinx 7.4 hinzugefügt. Vor Sphinx 7.4 sollten die folgenden Methoden zum Parsen von Inhalten verwendet werden

self.state.nested_parse
sphinx.util.nodes.nested_parse_with_titles() – dies ermöglicht Titel im analysierten Inhalt.

def run(self) -> list[Node]:
    container = docutils.nodes.Element()
    # either
    nested_parse_with_titles(self.state, self.result, container, self.content_offset)
    # or
    self.state.nested_parse(self.result, self.content_offset, container)
    parsed = container.children
    return parsed

Zum Parsen von Inline-Markup verwenden Sie parse_inline(). Dies darf nur für Text verwendet werden, der eine einzelne Zeile oder einen Absatz darstellt und keine strukturellen Elemente (Überschriften, Übergänge, Direktiven usw.) enthält.

Hinweis

sphinx.util.docutils.switch_source_input() ermöglicht die Änderung der Quelle (Eingabedatei) während des Parsens von Inhalt in einer Direktive. Dies ist nützlich für das Parsen von gemischtem Inhalt, wie z. B. in sphinx.ext.autodoc, wo es zum Parsen von Docstrings verwendet wird.

from sphinx.util.docutils import switch_source_input
from sphinx.util.parsing import nested_parse_to_nodes

# Switch source_input between parsing content.
# Inside this context, all parsing errors and warnings are reported as
# happened in new source_input (in this case, ``self.result``).
with switch_source_input(self.state, self.result):
    parsed = nested_parse_to_nodes(self.state, self.result)

Veraltet seit Version 1.7: Bis Sphinx 1.6 wurde dafür sphinx.ext.autodoc.AutodocReporter verwendet. Es wurde durch switch_source_input() ersetzt.

ViewLists und StringLists¶

Docutils stellt Dokumentenquellzeilen in der Klasse StringList dar, die von ViewList erbt, beide im Modul docutils.statemachine. Dies ist eine Liste mit erweiterter Funktionalität, einschließlich der Tatsache, dass Slicing Ansichten der ursprünglichen Liste erstellt und dass die Liste Informationen über Quellzeilennummern enthält.

Das Attribut Directive.content ist eine StringList. Wenn Sie Inhalt generieren, der als reStructuredText geparst werden soll, müssen Sie eine StringList für die Docutils-APIs erstellen. Die von Sphinx bereitgestellten Hilfsfunktionen erledigen dies automatisch. Wichtig für die Inhaltserstellung sind die folgenden Punkte

Der Konstruktor von ViewList nimmt eine Liste von Strings (Zeilen) und einen Quell-(Dokumenten-)Namen entgegen.
Die Methode ViewList.append() nimmt ebenfalls eine Zeile und einen Quellennamen entgegen.