Entwicklung von Autodoc-Erweiterungen¶

Ziel dieses Tutorials ist es, eine Erweiterung zu erstellen, die Unterstützung für einen neuen Typ für Autodoc hinzufügt. Diese Autodoc-Erweiterung formatiert die IntEnum-Klasse aus der Python-Standardbibliothek. (Modul enum)

Übersicht¶

Wir möchten eine Erweiterung, die eine automatische Dokumentation für IntEnum erstellt. IntEnum ist die Integer-Enum-Klasse aus dem Standardmodul enum.

Derzeit hat diese Klasse kein spezielles Autodoc-Verhalten.

Wir möchten Autodoc Folgendes hinzufügen:

Eine neue autointenum-Direktive, die die IntEnum-Klasse dokumentiert.
Die generierte Dokumentation enthält alle möglichen Enum-Werte mit Namen.
Die autointenum-Direktive hat eine Option :hex:, die dazu führt, dass die ganzen Zahlen in hexadezimaler Form ausgegeben werden.

Voraussetzungen¶

Wir benötigen die gleiche Einrichtung wie in den vorherigen Erweiterungen. Diesmal legen wir unsere Erweiterung in eine Datei namens autodoc_intenum.py. Die Datei my_enums.py enthält die Beispiel-Enums, die wir dokumentieren werden.

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

└── source
    ├── _ext
    │   └── autodoc_intenum.py
    ├── conf.py
    ├── index.rst
    └── my_enums.py

Schreiben der Erweiterung¶

Beginnen Sie mit der setup-Funktion für die Erweiterung.

def setup(app: Sphinx) -> ExtensionMetadata:
    app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
    app.add_autodocumenter(IntEnumDocumenter)
    return {
        'version': '1',
        'parallel_read_safe': True,
    }

Die Methode setup_extension() ruft die Autodoc-Erweiterung auf, da unsere neue Erweiterung von Autodoc abhängt. add_autodocumenter() ist die Methode, die unsere neue Autodokumentationsklasse registriert.

Wir möchten bestimmte Objekte aus der Autodoc-Erweiterung importieren

from __future__ import annotations

from enum import IntEnum
from typing import TYPE_CHECKING

from sphinx.ext.autodoc import ClassDocumenter, Documenter, bool_option

Es gibt verschiedene Dokumentationsklassen wie MethodDocumenter oder AttributeDocumenter in der Autodoc-Erweiterung, aber unsere neue Klasse ist eine Unterklasse von ClassDocumenter, einer Dokumentationsklasse, die von Autodoc zum Dokumentieren von Klassen verwendet wird.

Dies ist die Definition unserer neuen Autodokumentationsklasse

class IntEnumDocumenter(ClassDocumenter):
    objtype = 'intenum'
    directivetype = ClassDocumenter.objtype
    priority = 10 + ClassDocumenter.priority
    option_spec = dict(ClassDocumenter.option_spec)
    option_spec['hex'] = bool_option

    @classmethod
    def can_document_member(
        cls, member: Any, membername: str, isattr: bool, parent: Documenter
    ) -> bool:
        try:
            return issubclass(member, IntEnum)
        except TypeError:
            return False

    def add_directive_header(self, sig: str) -> None:
        super().add_directive_header(sig)
        self.add_line('   :final:', self.get_sourcename())

    def add_content(
        self,
        more_content: StringList | None,
    ) -> None:
        super().add_content(more_content)

        source_name = self.get_sourcename()
        enum_object: IntEnum = self.object
        use_hex = self.options.hex
        self.add_line('', source_name)

        for the_member_name, enum_member in enum_object.__members__.items():  # type: ignore[attr-defined]
            the_member_value = enum_member.value
            if use_hex:
                the_member_value = hex(the_member_value)

            self.add_line(f'**{the_member_name}**: {the_member_value}', source_name)
            self.add_line('', source_name)

Wichtige Attribute der neuen Klasse

objtype: Dieses Attribut bestimmt den Namen der auto-Direktive. In diesem Fall ist die Auto-Direktive autointenum.
directivetype: Dieses Attribut legt den Namen der generierten Direktive fest. In diesem Beispiel ist die generierte Direktive .. :py:class::.
priority: Je größer die Zahl, desto höher die Priorität. Wir möchten, dass unser Dokumentator eine höhere Priorität hat als die Elternklasse.
option_spec: Optionen-Spezifikationen. Wir kopieren die Optionen der Elternklasse und fügen eine neue Option hex hinzu.

Überschriebene Member

can_document_member: Dieser Member ist wichtig zu überschreiben. Er sollte True zurückgeben, wenn das übergebene Objekt von dieser Klasse dokumentiert werden kann.
add_directive_header: Diese Methode generiert den Direktiven-Header. Wir fügen die Direktiven-Option :final: hinzu. Denken Sie daran, super aufzurufen, sonst wird keine Direktive generiert.
add_content: Diese Methode generiert den Body der Klassendokumentation. Nach dem Aufruf der Super-Methode generieren wir Zeilen für die Enum-Beschreibung.

Verwenden der Erweiterung¶

Sie können nun die neue Autodoc-Direktive verwenden, um jede IntEnum zu dokumentieren.

Zum Beispiel haben Sie die folgende IntEnum

my_enums.py¶

class Colors(IntEnum):
    """Colors enumerator"""
    NONE = 0
    RED = 1
    GREEN = 2
    BLUE = 3

Dies ist die Dokumentationsdatei mit der Autodoc-Direktive

index.rst¶

.. autointenum:: my_enums.Colors

Weitere Lektüre¶

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