Erweiterung des Build-Prozesses¶

Ziel dieses Tutorials ist die Erstellung einer umfassenderen Erweiterung als die in Erweiterung der Syntax mit Rollen und Direktiven. Während dieser Leitfaden nur das Schreiben einer benutzerdefinierten Rolle und Direktive behandelte, behandelt dieser Leitfaden eine komplexere Erweiterung des Sphinx-Build-Prozesses; das Hinzufügen mehrerer Direktiven zusammen mit benutzerdefinierten Knoten, zusätzlichen Konfigurationswerten und benutzerdefinierten Ereignisbehandlern.

Zu diesem Zweck behandeln wir eine todo-Erweiterung, die Funktionen zum Einfügen von Todo-Einträgen in die Dokumentation hinzufügt und diese an einem zentralen Ort sammelt. Dies ähnelt der mit Sphinx verteilten Erweiterung sphinx.ext.todo.

Übersicht¶

Hinweis

Um das Design dieser Erweiterung zu verstehen, siehe Wichtige Objekte und Build-Phasen.

Wir möchten, dass die Erweiterung Sphinx Folgendes hinzufügt

Eine todo-Direktive, die einen Inhalt enthält, der mit „TODO“ markiert ist und nur in der Ausgabe angezeigt wird, wenn ein neuer Konfigurationswert gesetzt ist. Todo-Einträge sollten standardmäßig nicht in der Ausgabe enthalten sein.
Eine todolist-Direktive, die eine Liste aller Todo-Einträge im gesamten Dokumentation erstellt.

Dafür müssen wir Sphinx die folgenden Elemente hinzufügen

Neue Direktiven, genannt todo und todolist.
Neue Dokumentenstruktur-Knoten zur Darstellung dieser Direktiven, konventionell ebenfalls todo und todolist genannt. Wir bräuchten keine neuen Knoten, wenn die neuen Direktiven nur Inhalte erzeugen würden, die durch vorhandene Knoten darstellbar sind.
Ein neuer Konfigurationswert todo_include_todos (Konfigurationswertnamen sollten mit dem Erweiterungsnamen beginnen, um eindeutig zu bleiben), der steuert, ob Todo-Einträge in die Ausgabe gelangen.
Neue Ereignisbehandler: einer für das doctree-resolved-Ereignis, um die Todo- und Todolist-Knoten zu ersetzen, einer für env-merge-info, um Zwischenergebnisse aus parallelen Builds zusammenzuführen, und einer für env-purge-doc (der Grund dafür wird später behandelt).

Voraussetzungen¶

Wie bei Erweiterung der Syntax mit Rollen und Direktiven werden wir dieses Plugin nicht über PyPI vertreiben, daher benötigen wir wieder ein Sphinx-Projekt, das es aufrufen kann. Sie können ein vorhandenes Projekt verwenden oder mit sphinx-quickstart ein neues erstellen.

Wir gehen davon aus, dass Sie separate Quellcode- (source) und Build- (build) Ordner verwenden. Ihre Erweiterungsdatei könnte sich in jedem Ordner Ihres Projekts befinden. In unserem Fall gehen wir wie folgt vor

Erstellen Sie einen Ordner _ext im Ordner source
Erstellen Sie eine neue Python-Datei im Ordner _ext mit dem Namen todo.py

Hier ist ein Beispiel für die Ordnerstruktur, die Sie erhalten könnten

└── source
    ├── _ext
    │   └── todo.py
    ├── _static
    ├── conf.py
    ├── somefolder
    ├── index.rst
    ├── somefile.rst
    └── someotherfile.rst

Schreiben der Erweiterung¶

Öffnen Sie todo.py und fügen Sie den folgenden Code ein, den wir im Folgenden detailliert erläutern werden

from docutils import nodes
from docutils.parsers.rst import Directive

from sphinx.application import Sphinx
from sphinx.locale import _
from sphinx.util.docutils import SphinxDirective
from sphinx.util.typing import ExtensionMetadata


class todo(nodes.Admonition, nodes.Element):
    pass


class todolist(nodes.General, nodes.Element):
    pass


def visit_todo_node(self, node):
    self.visit_admonition(node)


def depart_todo_node(self, node):
    self.depart_admonition(node)


class TodolistDirective(Directive):
    def run(self):
        return [todolist('')]


class TodoDirective(SphinxDirective):
    # this enables content in the directive
    has_content = True

    def run(self):
        targetid = 'todo-%d' % self.env.new_serialno('todo')
        targetnode = nodes.target('', '', ids=[targetid])

        todo_node = todo('\n'.join(self.content))
        todo_node += nodes.title(_('Todo'), _('Todo'))
        todo_node += self.parse_content_to_nodes()

        if not hasattr(self.env, 'todo_all_todos'):
            self.env.todo_all_todos = []

        self.env.todo_all_todos.append({
            'docname': self.env.current_document.docname,
            'lineno': self.lineno,
            'todo': todo_node.deepcopy(),
            'target': targetnode,
        })

        return [targetnode, todo_node]


def purge_todos(app, env, docname):
    if not hasattr(env, 'todo_all_todos'):
        return

    env.todo_all_todos = [
        todo for todo in env.todo_all_todos if todo['docname'] != docname
    ]


def merge_todos(app, env, docnames, other):
    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []
    if hasattr(other, 'todo_all_todos'):
        env.todo_all_todos.extend(other.todo_all_todos)


def process_todo_nodes(app, doctree, fromdocname):
    if not app.config.todo_include_todos:
        for node in doctree.findall(todo):
            node.parent.remove(node)

    # Replace all todolist nodes with a list of the collected todos.
    # Augment each todo with a backlink to the original location.
    env = app.env

    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []

    for node in doctree.findall(todolist):
        if not app.config.todo_include_todos:
            node.replace_self([])
            continue

        content = []

        for todo_info in env.todo_all_todos:
            para = nodes.paragraph()
            filename = env.doc2path(todo_info['docname'], base=None)
            description = _(
                '(The original entry is located in %s, line %d and can be found '
            ) % (filename, todo_info['lineno'])
            para += nodes.Text(description)

            # Create a reference
            newnode = nodes.reference('', '')
            innernode = nodes.emphasis(_('here'), _('here'))
            newnode['refdocname'] = todo_info['docname']
            newnode['refuri'] = app.builder.get_relative_uri(
                fromdocname, todo_info['docname']
            )
            newnode['refuri'] += '#' + todo_info['target']['refid']
            newnode.append(innernode)
            para += newnode
            para += nodes.Text('.)')

            # Insert into the todolist
            content.extend((
                todo_info['todo'],
                para,
            ))

        node.replace_self(content)


def setup(app: Sphinx) -> ExtensionMetadata:
    app.add_config_value('todo_include_todos', False, 'html')

    app.add_node(todolist)
    app.add_node(
        todo,
        html=(visit_todo_node, depart_todo_node),
        latex=(visit_todo_node, depart_todo_node),
        text=(visit_todo_node, depart_todo_node),
    )

    app.add_directive('todo', TodoDirective)
    app.add_directive('todolist', TodolistDirective)
    app.connect('doctree-resolved', process_todo_nodes)
    app.connect('env-purge-doc', purge_todos)
    app.connect('env-merge-info', merge_todos)

    return {
        'version': '0.1',
        'env_version': 1,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

Dies ist eine weitaus umfangreichere Erweiterung als die in Erweiterung der Syntax mit Rollen und Direktiven beschriebene, jedoch werden wir jedes Stück Schritt für Schritt betrachten, um zu erklären, was passiert.

Die Knotenklassen

Beginnen wir mit den Knotenklassen

class todo(nodes.Admonition, nodes.Element):
    pass


class todolist(nodes.General, nodes.Element):
    pass


def visit_todo_node(self, node):
    self.visit_admonition(node)

Knotenklassen müssen normalerweise nichts tun, außer von den Standard-Docutils-Klassen zu erben, die in docutils.nodes definiert sind. todo erbt von Admonition, da es wie eine Notiz oder Warnung behandelt werden sollte, todolist ist lediglich ein „allgemeiner“ Knoten.

Hinweis

Viele Erweiterungen müssen keine eigenen Knotenklassen erstellen und funktionieren gut mit den bereits von docutils und Sphinx bereitgestellten Knoten.

Aufmerksamkeit

Es ist wichtig zu wissen, dass Sie Sphinx zwar erweitern können, ohne Ihre conf.py zu verlassen, wenn Sie dort einen geerbten Knoten deklarieren, Sie jedoch auf einen nicht offensichtlichen PickleError stoßen werden. Stellen Sie also bitte sicher, dass Sie geerbte Knoten in ein separates Python-Modul legen, wenn etwas schiefgeht.

Für weitere Details siehe

Die Direktivenklassen

Eine Direktivenklasse ist eine Klasse, die normalerweise von docutils.parsers.rst.Directive abgeleitet ist. Die Direktiven-Schnittstelle wird auch im docutils Dokumentation detailliert behandelt; wichtig ist, dass die Klasse Attribute zur Konfiguration der zulässigen Markup-Elemente und eine run-Methode enthält, die eine Liste von Knoten zurückgibt.

Betrachten wir zuerst die TodolistDirective-Direktive

class TodolistDirective(Directive):
    def run(self):
        return [todolist('')]

Sie ist sehr einfach und erstellt und gibt eine Instanz unserer todolist-Knotenklasse zurück. Die TodolistDirective-Direktive selbst hat weder Inhalt noch Argumente, die behandelt werden müssen. Damit kommen wir zur TodoDirective-Direktive

class TodoDirective(SphinxDirective):
    # this enables content in the directive
    has_content = True

    def run(self):
        targetid = 'todo-%d' % self.env.new_serialno('todo')
        targetnode = nodes.target('', '', ids=[targetid])

        todo_node = todo('\n'.join(self.content))
        todo_node += nodes.title(_('Todo'), _('Todo'))
        todo_node += self.parse_content_to_nodes()

        if not hasattr(self.env, 'todo_all_todos'):
            self.env.todo_all_todos = []

        self.env.todo_all_todos.append({
            'docname': self.env.current_document.docname,
            'lineno': self.lineno,
            'todo': todo_node.deepcopy(),
            'target': targetnode,
        })

        return [targetnode, todo_node]

Hier werden mehrere wichtige Dinge behandelt. Erstens erben wir jetzt, wie Sie sehen können, von der Hilfsklasse sphinx.util.docutils.SphinxDirective anstelle der üblichen Directive-Klasse. Dies gibt uns Zugriff auf die Build-Umgebungsinstanz über die Eigenschaft self.env. Ohne dies müssten wir das eher umständliche self.state.document.settings.env verwenden. Dann muss die TodoDirective-Direktive, um als Linkziel zu dienen (von TodolistDirective), zusätzlich zum todo-Knoten einen Zielknoten zurückgeben. Die Ziel-ID (in HTML wird dies der Ankername sein) wird durch die Verwendung von env.new_serialno generiert, die bei jedem Aufruf eine neue eindeutige Ganzzahl zurückgibt und daher eindeutige Zielnamen erzeugt. Der Zielknoten wird ohne Text instanziiert (die ersten beiden Argumente).

Beim Erstellen eines Admonition-Knotens wird der Inhaltskörper der Direktive mit self.parse_content_to_nodes() analysiert. Anschließend wird der todo-Knoten zur Umgebung hinzugefügt. Dies ist notwendig, um eine Liste aller Todo-Einträge im gesamten Dokumentation erstellen zu können, an der Stelle, an der der Autor eine todolist-Direktive platziert. Für diesen Fall wird das Umgebungsattribut todo_all_todos verwendet (auch hier sollte der Name eindeutig sein, daher wird er mit dem Erweiterungsnamen präfixiert). Es existiert nicht, wenn eine neue Umgebung erstellt wird, daher muss die Direktive dies prüfen und bei Bedarf erstellen. Verschiedene Informationen über den Speicherort des Todo-Eintrags werden zusammen mit einer Kopie des Knotens gespeichert.

In der letzten Zeile werden die Knoten zurückgegeben, die in den Doctree eingefügt werden sollen: der Zielknoten und der Admonition-Knoten.

Die von der Direktive zurückgegebene Knotenstruktur sieht wie folgt aus

+--------------------+
| target node        |
+--------------------+
+--------------------+
| todo node          |
+--------------------+
  \__+--------------------+
     | admonition title   |
     +--------------------+
     | paragraph          |
     +--------------------+
     | ...                |
     +--------------------+

Die Ereignisbehandler

Ereignisbehandler sind eines der mächtigsten Features von Sphinx und bieten eine Möglichkeit, sich in jeden Teil des Dokumentationsprozesses einzuhaken. Es gibt viele von Sphinx selbst bereitgestellte Ereignisse, wie im API-Handbuch beschrieben, und wir werden hier eine Teilmenge davon verwenden.

Schauen wir uns die im obigen Beispiel verwendeten Ereignisbehandler an. Zuerst den für das env-purge-doc-Ereignis

def purge_todos(app, env, docname):
    if not hasattr(env, 'todo_all_todos'):
        return

    env.todo_all_todos = [
        todo for todo in env.todo_all_todos if todo['docname'] != docname
    ]

Da wir Informationen aus Quelldateien in der persistenten Umgebung speichern, können diese veraltet sein, wenn sich die Quelldatei ändert. Daher werden vor dem Lesen jeder Quelldatei die Aufzeichnungen der Umgebung darüber gelöscht, und das env-purge-doc-Ereignis gibt Erweiterungen die Möglichkeit, dasselbe zu tun. Hier löschen wir alle Todos, deren docname mit dem angegebenen übereinstimmt, aus der todo_all_todos-Liste. Wenn noch Todos im Dokument verbleiben, werden diese während des Parsens erneut hinzugefügt.

Der nächste Behandler, für das env-merge-info-Ereignis, wird während paralleler Builds verwendet. Da bei parallelen Builds alle Threads ihre eigene env haben, gibt es mehrere todo_all_todos-Listen, die zusammengeführt werden müssen

def merge_todos(app, env, docnames, other):
    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []
    if hasattr(other, 'todo_all_todos'):
        env.todo_all_todos.extend(other.todo_all_todos)

Der andere Behandler gehört zum doctree-resolved-Ereignis

def process_todo_nodes(app, doctree, fromdocname):
    if not app.config.todo_include_todos:
        for node in doctree.findall(todo):
            node.parent.remove(node)

    # Replace all todolist nodes with a list of the collected todos.
    # Augment each todo with a backlink to the original location.
    env = app.env

    if not hasattr(env, 'todo_all_todos'):
        env.todo_all_todos = []

    for node in doctree.findall(todolist):
        if not app.config.todo_include_todos:
            node.replace_self([])
            continue

        content = []

        for todo_info in env.todo_all_todos:
            para = nodes.paragraph()
            filename = env.doc2path(todo_info['docname'], base=None)
            description = _(
                '(The original entry is located in %s, line %d and can be found '
            ) % (filename, todo_info['lineno'])
            para += nodes.Text(description)

            # Create a reference
            newnode = nodes.reference('', '')
            innernode = nodes.emphasis(_('here'), _('here'))
            newnode['refdocname'] = todo_info['docname']
            newnode['refuri'] = app.builder.get_relative_uri(
                fromdocname, todo_info['docname']
            )
            newnode['refuri'] += '#' + todo_info['target']['refid']
            newnode.append(innernode)
            para += newnode
            para += nodes.Text('.)')

            # Insert into the todolist
            content.extend((
                todo_info['todo'],
                para,
            ))

        node.replace_self(content)

Das doctree-resolved-Ereignis wird für jedes Dokument ausgelöst, das am Ende von Phase 3 (Auflösung) geschrieben werden soll, und ermöglicht die benutzerdefinierte Auflösung für dieses Dokument. Der Behandler, den wir für dieses Ereignis geschrieben haben, ist etwas komplexer. Wenn der Konfigurationswert todo_include_todos (den wir kurz beschreiben werden) falsch ist, werden alle todo- und todolist-Knoten aus den Dokumenten entfernt. Wenn nicht, bleiben die todo-Knoten dort und so, wie sie sind. todolist-Knoten werden durch eine Liste von Todo-Einträgen ersetzt, komplett mit Backlinks zum Speicherort, von dem sie stammen. Die Listenpunkte bestehen aus den Knoten des todo-Eintrags und dynamisch erstellten Docutils-Knoten: ein Absatz für jeden Eintrag, der Text enthält, der den Speicherort angibt, und ein Link (Referenzknoten, der einen kursiven Knoten enthält) mit der Rückreferenz. Die Referenz-URI wird von sphinx.builders.Builder.get_relative_uri() erstellt, die eine geeignete URI basierend auf dem verwendeten Builder erstellt, und die ID des Todo-Knotens (des Ziels) als Ankernamen angehängt.

Die setup Funktion

Wie bereits erwähnt (vorher), ist die Funktion setup eine Voraussetzung und wird zum Einbinden von Direktiven in Sphinx verwendet. Wir verwenden sie aber auch, um die anderen Teile unserer Erweiterung zu verbinden. Schauen wir uns unsere setup-Funktion an

def setup(app: Sphinx) -> ExtensionMetadata:
    app.add_config_value('todo_include_todos', False, 'html')

    app.add_node(todolist)
    app.add_node(
        todo,
        html=(visit_todo_node, depart_todo_node),
        latex=(visit_todo_node, depart_todo_node),
        text=(visit_todo_node, depart_todo_node),
    )

    app.add_directive('todo', TodoDirective)
    app.add_directive('todolist', TodolistDirective)
    app.connect('doctree-resolved', process_todo_nodes)
    app.connect('env-purge-doc', purge_todos)
    app.connect('env-merge-info', merge_todos)

    return {
        'version': '0.1',
        'env_version': 1,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

Die Aufrufe in dieser Funktion beziehen sich auf die zuvor hinzugefügten Klassen und Funktionen. Was die einzelnen Aufrufe tun, ist Folgendes

add_config_value() teilt Sphinx mit, dass es den neuen *Konfigurationswert* todo_include_todos erkennen soll, dessen Standardwert False ist (was Sphinx auch mitteilt, dass es sich um einen booleschen Wert handelt).

Wenn das dritte Argument 'html' wäre, würden HTML-Dokumente vollständig neu aufgebaut, wenn sich der Konfigurationswert ändert. Dies ist für Konfigurationswerte erforderlich, die das Lesen beeinflussen (Phase 1 (Lesen) des Builds).
add_node() fügt dem Build-System eine neue *Knotenklasse* hinzu. Es kann auch Besucherfunktionen für jedes unterstützte Ausgabeformat angeben. Diese Besucherfunktionen sind erforderlich, wenn die neuen Knoten bis Phase 4 (Schreiben) bestehen bleiben. Da der todolist-Knoten immer in Phase 3 (Auflösung) ersetzt wird, benötigt er keine.
add_directive() fügt eine neue *Direktive* hinzu, gegeben durch Name und Klasse.
Schließlich fügt connect() einen *Ereignisbehandler* zum Ereignis hinzu, dessen Name durch das erste Argument gegeben ist. Die Ereignisbehandler-Funktion wird mit mehreren Argumenten aufgerufen, die mit dem Ereignis dokumentiert sind.

Damit ist unsere Erweiterung abgeschlossen.

Verwenden der Erweiterung¶

Wie zuvor müssen wir die Erweiterung aktivieren, indem wir sie in unserer conf.py-Datei deklarieren. Hierfür sind zwei Schritte erforderlich

Fügen Sie das Verzeichnis _ext mit sys.path.append zum Python-Pfad hinzu. Dies sollte am Anfang der Datei platziert werden.
Aktualisieren oder erstellen Sie die Liste extensions und fügen Sie den Namen der Erweiterungsdatei zur Liste hinzu

Zusätzlich können wir den Konfigurationswert todo_include_todos setzen wollen. Wie oben erwähnt, ist dieser standardmäßig False, aber wir können ihn explizit setzen.

Zum Beispiel

import sys
from pathlib import Path

sys.path.append(str(Path('_ext').resolve()))

extensions = ['todo']

todo_include_todos = False

Sie können die Erweiterung nun in Ihrem gesamten Projekt verwenden. Zum Beispiel

index.rst¶

Hello, world
============

.. toctree::
   somefile.rst
   someotherfile.rst

Hello world. Below is the list of TODOs.

.. todolist::

somefile.rst¶

foo
===

Some intro text here...

.. todo:: Fix this

someotherfile.rst¶

bar
===

Some more text here...

.. todo:: Fix that

Da wir todo_include_todos auf False gesetzt haben, werden wir für die Direktiven todo und todolist tatsächlich nichts gerendert sehen. Wenn wir dies jedoch auf true setzen, sehen wir die zuvor beschriebene Ausgabe.

Weitere Lektüre¶

Weitere Informationen finden Sie in der docutils-Dokumentation und in der Sphinx API.

Wenn Sie Ihre Erweiterung über mehrere Projekte oder mit anderen teilen möchten, lesen Sie den Abschnitt Drittanbieter-Erweiterungen.