sphinx.ext.autodoc – Dokumentation aus Docstrings einbinden

Diese Erweiterung kann die zu dokumentierenden Module importieren und die Dokumentation aus Docstrings auf halbautomatische Weise extrahieren.

Warnung

autodoc **importiert** die zu dokumentierenden Module. Wenn Module Nebeneffekte beim Import haben, werden diese von autodoc ausgeführt, wenn sphinx-build aufgerufen wird.

Wenn Sie Skripte (im Gegensatz zu Bibliotheksmodulen) dokumentieren, stellen Sie sicher, dass die Hauptroutine durch eine if __name__ == '__main__' Bedingung geschützt ist.

Damit dies funktioniert, müssen die Docstrings natürlich in korrektem reStructuredText geschrieben sein. Sie können dann alle üblichen Sphinx-Markierungen in den Docstrings verwenden, und diese werden korrekt in der Dokumentation erscheinen. Zusammen mit handgeschriebener Dokumentation erleichtert diese Technik den Aufwand, zwei Dokumentationsorte pflegen zu müssen, und vermeidet gleichzeitig rein API-generierte Dokumentation, die wie automatisch generiert aussieht.

Wenn Sie NumPy oder Google Style Docstrings gegenüber reStructuredText bevorzugen, können Sie auch die Erweiterung napoleon aktivieren. napoleon ist ein Präprozessor, der Docstrings vor der Verarbeitung durch autodoc in korrektes reStructuredText umwandelt.

Erste Schritte

Einrichtung

Aktivieren Sie das Plugin, indem Sie 'sphinx.ext.autodoc' zur extensions-Liste in conf.py hinzufügen.

extensions = [
    ...
    'sphinx.ext.autodoc',
]

Sicherstellen, dass der Code importiert werden kann

autodoc analysiert den Code und die Docstrings durch Introspektion, nachdem **die Module importiert** wurden. Damit der Import funktioniert, müssen Sie sicherstellen, dass Ihre Module von Sphinx gefunden werden können und Abhängigkeiten aufgelöst werden können (wenn Ihr Modul import foo ausführt, aber foo in der Python-Umgebung, in der Sphinx läuft, nicht verfügbar ist, schlägt der Import Ihres Moduls fehl).

Es gibt zwei Möglichkeiten, dies sicherzustellen:

  1. Verwenden Sie eine Umgebung, die Ihr Paket und Sphinx enthält. Dies kann z.B. Ihre lokale Entwicklungsumgebung sein (mit einer editierbaren Installation) oder eine Umgebung in CI, in der Sie Sphinx und Ihr Paket installieren. Der reguläre Installationsprozess stellt sicher, dass Ihr Paket von Sphinx gefunden werden kann und alle Abhängigkeiten verfügbar sind.

  2. Es ist alternativ möglich, den Sphinx-Lauf zu patchen, damit er direkt auf den Quellen operieren kann; z.B. wenn Sie einen Sphinx-Build aus einem Quell-Checkout durchführen möchten.

    • Patchen Sie sys.path in conf.py, um Ihren Quellpfad einzuschließen. Wenn Sie beispielsweise eine Repository-Struktur mit doc/conf.py und Ihr Paket unter src/my_package haben, sollten Sie Folgendes zu Ihrer conf.py hinzufügen.

      import sys
from pathlib import Path

sys.path.insert(0, str(Path('..', 'src').resolve()))

    • Um fehlende Abhängigkeiten zu bewältigen, geben Sie die fehlenden Module in der Einstellung autodoc_mock_imports an.

Verwendung

Sie können nun die Direktiven verwenden, um formatierte Dokumentation für Python-Codeelemente wie Funktionen, Klassen, Module usw. hinzuzufügen. Um beispielsweise die Funktion io.open() zu dokumentieren und ihre Signatur und Docstring aus der Quelldatei zu lesen, würden Sie schreiben:

.. autofunction:: io.open

Sie können auch ganze Klassen oder sogar Module automatisch dokumentieren, indem Sie Member-Optionen für die Auto-Direktiven verwenden, wie z.B.:

.. automodule:: io
   :members:

Tipp

Als Hinweis für die Autodoc-Erweiterung können Sie einen ::-Separator zwischen dem Modulnamen und dem Objektnamen einfügen, damit Autodoc das richtige Modul kennt, falls es mehrdeutig ist.

.. autoclass:: module.name::Noodle

Objekte als öffentlich oder privat markieren

  • autodoc betrachtet ein Mitglied als privat, wenn sein Docstring :meta private: in seinen Info-Feldlisten enthält. Zum Beispiel:

    def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """

    Hinzugefügt in Version 3.0.

  • autodoc betrachtet ein Mitglied als öffentlich, wenn sein Docstring :meta public: in seinen Info-Feldlisten enthält, auch wenn es mit einem Unterstrich beginnt. Zum Beispiel:

    def _my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta public:
    """

    Hinzugefügt in Version 3.1.

  • autodoc betrachtet ein Variablenmitglied, das keinen Standardwert hat, als zu versteckend, wenn sein Docstring :meta hide-value: in seinen Info-Feldlisten enthält. Beispiel:

    var1 = None  #: :meta hide-value:

    Hinzugefügt in Version 3.5.

Doc-Kommentare und Docstrings

Python hat keine eingebaute Unterstützung für Docstrings für Moduldatenmitglieder oder Klassenattribute. Um diese dokumentieren zu können, erkennt autodoc ein spezielles Format eines Kommentars, das als „Doc-Kommentar“ oder „Dokumentationskommentar“ bezeichnet wird.

Diese Kommentare beginnen mit einem Doppelpunkt und einem optionalen Leerzeichen, '#:' oder '#: '. Um erkannt zu werden, müssen die Kommentare entweder in derselben Zeile wie die Variable oder in einer oder mehreren Zeilen vor der Variable erscheinen. Mehrzeilige Doc-Kommentare müssen immer in den Zeilen vor der Definition der Variable stehen.

Zum Beispiel haben alle drei der folgenden Variablen gültige Doc-Kommentare:

egg_and_spam = 1.50  #: A simple meal

#: Spam! Lovely spam! Lovely spam!
egg_bacon_sausage_and_spam = 2.49

#: Truly gourmet cuisine for madam; Lobster Thermidor
#: aux Crevettes with a mornay sauce garnished with
#: truffle pate, brandy and a fried egg on top and spam.
lobster_thermidor = 35.00

Alternativ kann autodoc einen Docstring in der Zeile unmittelbar nach der Definition erkennen.

In der folgenden Klassendefinition haben alle Attribute eine von autodoc erkannte Dokumentation:

class Foo:
    """Docstring for class Foo."""

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self):
        #: Doc comment for instance attribute qux.
        self.qux = 3

        self.spam = 4
        """Docstring for instance attribute spam."""

Direktiven

autodoc bietet mehrere Direktiven, die Versionen der üblichen py:module, py:class und so weiter sind. Beim Parsen importieren sie das entsprechende Modul und extrahieren den Docstring der gegebenen Objekte, wobei sie diese unter einer geeigneten py:module, py:class etc. Direktive in die Seitenquelle einfügen.

Hinweis

So wie py:class das aktuelle py:module berücksichtigt, tut dies auch autoclass. Ebenso berücksichtigt automethod die aktuelle py:class.

Standard-Direktivenoptionen

Um eine der unten beschriebenen Optionen zur Standardeinstellung zu machen, verwenden Sie das Dictionary autodoc_default_options in conf.py.

Wenn Sie Standardwerte für die Optionen :members:, :exclude-members:, :private-members: oder :special-members: verwenden, überschreibt die Einstellung der Option in einer Direktive den Standardwert. Um stattdessen die Standardliste mit der pro-Direktiven Option zu erweitern, kann die Liste mit einem Pluszeichen (+) eingeleitet werden, wie folgt:

.. autoclass:: Noodle
   :members: eat
   :private-members: +_spicy, _garlickly

Tipp

Bei Verwendung von autodoc_default_options können die Standardwerte pro Direktive mit der negierten Form :no-option: als Option der Direktive deaktiviert werden. Zum Beispiel:

.. automodule:: foo
   :no-undoc-members:

Module automatisch dokumentieren

.. automodule::

Dokumentiert ein Modul. Standardmäßig fügt die Direktive nur den Docstring des Moduls selbst ein.

.. automodule:: noodles

würde folgenden Quellcode erzeugen:

.. py:module:: noodles

   The noodles module.

Die Direktive kann auch eigenen Inhalt enthalten, der in den resultierenden Nicht-Auto-Direktiven-Quellcode nach dem Docstring (aber vor jeder automatischen Mitgliedsdokumentation) eingefügt wird.

Daher können Sie auch automatische und nicht-automatische Mitgliedsdokumentation mischen, wie folgt:

.. automodule:: noodles
   :members: Noodle

   .. py:function:: boiled_noodle(time=10)

      Create a noodle that has been boiled for *time* minutes.

Optionen

:no-index:

Erzeugt keinen Indexeintrag für das dokumentierte Modul oder für automatisch dokumentierte Mitglieder.

Hinzugefügt in Version 0.4.

:no-index-entry:

Erzeugt keinen Indexeintrag für das dokumentierte Modul oder für automatisch dokumentierte Mitglieder. Im Gegensatz zu :no-index: werden Querverweise weiterhin erstellt.

Hinzugefügt in Version 8.2.

:platform: platforms (komma-separierte Liste)

Gibt Plattformen an, auf denen das Modul verfügbar ist. Dies ist identisch mit der :platform: Option der py:module Direktive.

:synopsis: purpose (text)

Ein Satz, der den Zweck des Moduls beschreibt. Dies ist identisch mit der :synopsis: Option der py:module Direktive.

Hinzugefügt in Version 0.5.

:deprecated:

Markiert ein Modul als veraltet. Dies ist identisch mit der :deprecated: Option der py:module Direktive.

Hinzugefügt in Version 0.5.

:ignore-module-all: (kein Wert)

Verwendet __all__ nicht, wenn das zu dokumentierende Modul analysiert wird.

Hinzugefügt in Version 1.7.

Optionen zur Auswahl von zu dokumentierenden Mitgliedern

:members: (kein Wert oder komma-separierte Liste)

Erstellt automatische Dokumentation für alle Mitglieder des Zielmoduls.

.. automodule:: noodles
   :members:

Standardmäßig schließt autodoc nur öffentliche Mitglieder mit einem Docstring oder Doc-Kommentar (#:) ein. Wenn __all__ existiert, wird es verwendet, um zu definieren, welche Mitglieder öffentlich sind, es sei denn, die Option :ignore-module-all: ist gesetzt.

Um nur bestimmte Mitglieder zu dokumentieren, kann eine explizite, komma-separierte Liste als Argument für :members: verwendet werden.

.. automodule:: noodles
   :members: Noodle
:exclude-members: (komma-separierte Liste)

Schließt die angegebenen Namen von den zu dokumentierenden Mitgliedern aus. Zum Beispiel:

.. automodule:: noodles
   :members:
   :exclude-members: NoodleBase

Hinzugefügt in Version 0.6.

:imported-members: (kein Wert)

Um die Dokumentation von importierten Klassen oder Funktionen in einer automodule Direktive mit der Option members zu verhindern, werden nur Modulmitglieder dokumentiert, bei denen das Attribut __module__ mit dem an automodule übergebenen Modulnamen übereinstimmt.

Setzen Sie die Option imported-members, wenn Sie dieses Verhalten verhindern und alle verfügbaren Mitglieder dokumentieren möchten.

Beachten Sie, dass Attribute aus importierten Modulen nicht dokumentiert werden, da die Attributdokumentation durch Parsen der Quelldatei des aktuellen Moduls ermittelt wird.

Hinzugefügt in Version 1.2.

:undoc-members:

Erstellt automatische Dokumentation für Mitglieder des Zielmoduls, die keinen Docstring oder Doc-Kommentar haben. Zum Beispiel:

.. automodule:: noodles
   :members:
   :undoc-members:
:private-members: (kein Wert oder komma-separierte Liste)

Erstellt automatische Dokumentation für private Mitglieder des Zielmoduls. Dies schließt Namen mit führendem Unterstrich (z.B. _private) und solche Mitglieder ein, die explizit als privat mit :meta private: markiert sind.

.. automodule:: noodles
   :members:
   :private-members:

Um nur bestimmte private Mitglieder zu dokumentieren, kann eine explizite, komma-separierte Liste als Argument für :private-members: verwendet werden.

.. automodule:: noodles
   :members:
   :private-members: _spicy, _garlickly

Hinzugefügt in Version 1.1.

Geändert in Version 3.2: Die Option kann jetzt ein Argument als komma-separierte Liste annehmen.

:special-members: (kein Wert oder komma-separierte Liste)

Erstellt automatische Dokumentation für spezielle Mitglieder des Zielmoduls, auch bekannt als "Dunder"-Namen. Dies schließt alle Namen ein, die von doppelten Unterstrichen umschlossen sind, z.B. __special__.

.. automodule:: my.Class
   :members:
   :special-members:

Um nur bestimmte spezielle Mitglieder zu dokumentieren, kann eine explizite, komma-separierte Liste als Argument für :special-members: verwendet werden.

.. automodule:: noodles
   :members:
   :special-members: __version__

Hinzugefügt in Version 1.1.

Geändert in Version 1.2: Die Option kann jetzt ein Argument als komma-separierte Liste annehmen.

Optionen für dokumentierte Mitglieder

:member-order: (alphabetisch, bysource, oder groupwise)

Wählt die Reihenfolge der automatisch dokumentierten Mitglieder (Standard: alphabetical). Dies überschreibt die Einstellung autodoc_member_order.

  • alphabetical: Verwendet einfache alphabetische Reihenfolge.

  • groupwise: Gruppiert nach Objekttyp (Klasse, Funktion usw.), verwendet alphabetische Reihenfolge innerhalb der Gruppen.

  • bysource: Verwendet die Reihenfolge der Objekte im Quellcode des Moduls. Die Variable __all__ kann verwendet werden, um diese Reihenfolge zu überschreiben.

Beachten Sie, dass für die Quellreihenfolge das Modul ein Python-Modul mit verfügbarem Quellcode sein muss.

Hinzugefügt in Version 0.6.

Geändert in Version 1.0: Unterstützt die Option 'bysource'.

:show-inheritance: (kein Wert)

Aktiviert die Option :show-inheritance: für alle Mitglieder des Moduls, wenn :members: aktiviert ist.

Hinzugefügt in Version 0.4.

Klassen oder Exceptions automatisch dokumentieren

.. autoclass::
.. autoexception::

Dokumentiert eine Klasse. Für Exception-Klassen ist .. autoexception:: zu bevorzugen. Standardmäßig fügt die Direktive nur den Docstring der Klasse selbst ein.

.. autoclass:: noodles.Noodle

würde folgenden Quellcode erzeugen:

.. py:class:: Noodle

   The Noodle class's docstring.

Die Direktive kann auch eigenen Inhalt enthalten, der in den resultierenden Nicht-Auto-Direktiven-Quellcode nach dem Docstring (aber vor jeder automatischen Mitgliedsdokumentation) eingefügt wird.

Daher können Sie auch automatische und nicht-automatische Mitgliedsdokumentation mischen, wie folgt:

.. autoclass:: noodles.Noodle
   :members: eat, slurp

   .. py:method:: boil(time=10)

      Boil the noodle for *time* minutes.

Erweiterte Nutzung

  • Es ist möglich, die Signatur für explizit dokumentierte aufrufbare Objekte (Funktionen, Methoden, Klassen) mit der regulären Syntax zu überschreiben, die die aus der Introspektion gewonnene Signatur überschreiben wird.

    .. autoclass:: noodles.Noodle(type)

   .. automethod:: eat(persona)

    Dies ist nützlich, wenn die Signatur der Methode durch einen Dekorator versteckt ist.

    Hinzugefügt in Version 0.4.

Optionen

:no-index:

Erzeugt keinen Indexeintrag für die dokumentierte Klasse oder für automatisch dokumentierte Mitglieder.

Hinzugefügt in Version 0.4.

:no-index-entry:

Erzeugt keinen Indexeintrag für die dokumentierte Klasse oder für automatisch dokumentierte Mitglieder. Im Gegensatz zu :no-index: werden Querverweise weiterhin erstellt.

Hinzugefügt in Version 8.2.

:class-doc-from: (class, init, oder beides)

Wählt aus, welcher Docstring für den Hauptteil der Direktive verwendet wird. Dies überschreibt den globalen Wert von autoclass_content. Die möglichen Werte sind:

  • class: Verwendet nur den Docstring der Klasse. Die Methode __init__() kann separat mit der Option :members: oder der automethod Direktive dokumentiert werden.

  • init: Verwendet nur den Docstring der Methode __init__().

  • both: Verwendet beide, indem der Docstring der Methode __init__() an den Klassen-Docstring angehängt wird.

Wenn die Methode __init__() nicht existiert oder einen leeren Docstring hat, versucht autodoc, den Docstring der Methode __new__() zu verwenden, falls diese existiert und nicht leer ist.

Hinzugefügt in Version 4.1.

Optionen zur Auswahl von zu dokumentierenden Mitgliedern

:members: (kein Wert oder komma-separierte Liste)

Erstellt automatische Dokumentation für alle Mitglieder der Zielklasse.

.. autoclass:: noodles.Noodle
   :members:

Standardmäßig schließt autodoc nur öffentliche Mitglieder mit einem Docstring oder Doc-Kommentar (#:) ein, die Attribute der Zielklasse sind (d.h. nicht geerbt).

Um nur bestimmte Mitglieder zu dokumentieren, kann eine explizite, komma-separierte Liste als Argument für :members: verwendet werden.

.. autoclass:: noodles.Noodle
   :members: eat, slurp
:exclude-members: (komma-separierte Liste)

Schließt die angegebenen Namen von den zu dokumentierenden Mitgliedern aus. Zum Beispiel:

.. autoclass:: noodles.Noodle
   :members:
   :exclude-members: prepare

Hinzugefügt in Version 0.6.

:inherited-members: (komma-separierte Liste)

Um automatische Dokumentation für von Basisklassen geerbte Mitglieder zu erstellen, verwenden Sie die Option :inherited-members:.

.. autoclass:: noodles.Noodle
   :members:
   :inherited-members:

Dies kann mit der Option :undoc-members: kombiniert werden, um automatische Dokumentation für **alle** verfügbaren Mitglieder der Klasse zu erstellen.

Die Mitglieder von Klassen, die in der übergebenen Liste für :inherited-members: aufgeführt sind, werden von der automatischen Dokumentation ausgeschlossen. Standardmäßig ist dies object, wenn kein Argument bereitgestellt wird, was bedeutet, dass Mitglieder der Klasse object nicht dokumentiert werden. Um diese einzuschließen, verwenden Sie None als Argument.

Beispiel: Wenn Ihre Klasse MyList von der Klasse list abgeleitet ist und Sie list.__len__() nicht dokumentieren möchten, sollten Sie die Option :inherited-members: list angeben, um spezielle Mitglieder der Listenklasse zu vermeiden.

Hinweis

Sollten geerbte Mitglieder ein anderes Format als reStructuredText für ihre Docstrings verwenden, kann dies zu Markup-Warnungen oder Fehlern führen.

Hinzugefügt in Version 0.3.

Geändert in Version 3.0: :inherited-members: nimmt nun den Namen einer Basisklasse, die ausgeschlossen werden soll, als Argument an.

Geändert in Version 5.0: Eine komma-separierte Liste von Basisklassennamen kann verwendet werden.

:undoc-members: (kein Wert)

Erstellt automatische Dokumentation für Mitglieder der Zielklasse, die keinen Docstring oder Doc-Kommentar haben. Zum Beispiel:

.. autoclass:: noodles.Noodle
   :members:
   :undoc-members:
:private-members: (kein Wert oder komma-separierte Liste)

Erstellt automatische Dokumentation für private Mitglieder der Zielklasse. Dies schließt Namen mit führendem Unterstrich (z.B. _private) und solche Mitglieder ein, die explizit als privat mit :meta private: markiert sind.

.. autoclass:: noodles.Noodle
   :members:
   :private-members:

Um nur bestimmte private Mitglieder zu dokumentieren, kann eine explizite, komma-separierte Liste als Argument für :private-members: verwendet werden.

.. autoclass:: noodles.Noodle
   :members:
   :private-members: _spicy, _garlickly

Hinzugefügt in Version 1.1.

Geändert in Version 3.2: Die Option kann jetzt Argumente annehmen.

:special-members: (kein Wert oder komma-separierte Liste)

Erstellt automatische Dokumentation für spezielle Mitglieder der Zielklasse, auch bekannt als "Dunder"-Namen. Dies schließt alle Namen ein, die von doppelten Unterstrichen umschlossen sind, z.B. __special__.

.. autoclass:: noodles.Noodle
   :members:
   :special-members:

Um nur bestimmte spezielle Mitglieder zu dokumentieren, kann eine explizite, komma-separierte Liste als Argument für :special-members: verwendet werden.

.. autoclass:: noodles.Noodle
   :members:
   :special-members: __init__, __name__

Hinzugefügt in Version 1.1.

Geändert in Version 1.2: Die Option kann jetzt ein Argument als komma-separierte Liste annehmen.

Optionen für dokumentierte Mitglieder

:member-order: (alphabetisch, bysource, oder groupwise)

Wählt die Reihenfolge der automatisch dokumentierten Mitglieder (Standard: alphabetical). Dies überschreibt die Einstellung autodoc_member_order.

  • 'alphabetical': Verwendet einfache alphabetische Reihenfolge.

  • 'groupwise': Gruppiert nach Objekttyp (Klasse, Funktion usw.), verwendet alphabetische Reihenfolge innerhalb der Gruppen.

  • 'bysource': Verwendet die Reihenfolge der Objekte im Quellcode des Moduls. Die Variable __all__ kann verwendet werden, um diese Reihenfolge zu überschreiben.

Beachten Sie, dass für die Quellreihenfolge das Modul ein Python-Modul mit verfügbarem Quellcode sein muss.

Hinzugefügt in Version 0.6.

Geändert in Version 1.0: Unterstützt die Option 'bysource'.

:show-inheritance: (kein Wert)

Fügt die Basisklassen der Klasse nach der Klassensignatur ein.

Hinzugefügt in Version 0.4.

Funktionsähnliche Objekte automatisch dokumentieren

.. autofunction::
.. automethod::
.. autoproperty::
.. autodecorator::

Dokumentiert eine Funktion, Methode, Eigenschaft oder einen Dekorator. Standardmäßig fügt die Direktive nur den Docstring der Funktion selbst ein.

.. autofunction:: noodles.average_noodle

würde folgenden Quellcode erzeugen:

.. py:function:: noodles.average_noodle

   The average_noodle function's docstring.

Die Direktive kann auch eigenen Inhalt enthalten, der in den resultierenden Nicht-Auto-Direktiven-Quellcode nach dem Docstring eingefügt wird.

Daher können Sie auch automatische und nicht-automatische Dokumentation mischen, wie folgt:

.. autofunction:: noodles.average_noodle

   .. note:: For more flexibility, use the :py:class:`!Noodle` class.

Hinzugefügt in Version 2.0: autodecorator.

Hinzugefügt in Version 2.1: autoproperty.

Hinweis

Wenn Sie dekorierte Funktionen oder Methoden dokumentieren, bedenken Sie, dass autodoc seine Docstrings durch Importieren des Moduls und Inspizieren des __doc__ Attributs der gegebenen Funktion oder Methode abruft. Das bedeutet, dass, wenn ein Dekorator die dekorierte Funktion durch eine andere ersetzt, er den ursprünglichen __doc__ auf die neue Funktion kopieren muss.

Erweiterte Nutzung

  • Es ist möglich, die Signatur für explizit dokumentierte aufrufbare Objekte (Funktionen, Methoden, Klassen) mit der regulären Syntax zu überschreiben, die die aus der Introspektion gewonnene Signatur überschreiben wird.

    .. autoclass:: Noodle(type)

   .. automethod:: eat(persona)

    Dies ist nützlich, wenn die Signatur der Methode durch einen Dekorator versteckt ist.

    Hinzugefügt in Version 0.4.

Optionen

:no-index:

Erzeugt keinen Indexeintrag für die dokumentierte Funktion.

Hinzugefügt in Version 0.4.

:no-index-entry:

Erzeugt keinen Indexeintrag für die dokumentierte Funktion. Im Gegensatz zu :no-index: werden Querverweise weiterhin erstellt.

Hinzugefügt in Version 8.2.

Attribute oder Daten automatisch dokumentieren

.. autodata::
.. autoattribute::

Dokumentiert eine Modulvariable oder Konstante ('data') oder ein Klassenattribut. Standardmäßig fügt die Direktive nur den Docstring der Variablen selbst ein.

.. autodata:: noodles.FLOUR_TYPE

würde folgenden Quellcode erzeugen:

.. py:data:: noodles.FLOUR_TYPE

   The FLOUR_TYPE constant's docstring.

Die Direktive kann auch eigenen Inhalt enthalten, der in den resultierenden Nicht-Auto-Direktiven-Quellcode nach dem Docstring eingefügt wird.

Daher können Sie auch automatische und nicht-automatische Mitgliedsdokumentation mischen, wie folgt:

.. autodata:: noodles.FLOUR_TYPE

   .. hint:: Cooking time can vary by which flour type is used.

Geändert in Version 0.6: autodata und autoattribute können nun Docstrings extrahieren.

Geändert in Version 1.1: Doc-Kommentare sind nun auf derselben Zeile einer Zuweisung erlaubt.

Optionen

:no-index:

Erstellt keinen Indexeintrag für die dokumentierte Variable oder Konstante.

Hinzugefügt in Version 0.4.

:no-index-entry:

Erstellt keinen Indexeintrag für die dokumentierte Variable oder Konstante. Im Gegensatz zu :no-index: werden Querverweise weiterhin erstellt.

Hinzugefügt in Version 8.2.

:annotation: value (string)

Hinzugefügt in Version 1.2.

Standardmäßig versucht autodoc, die Typ-Annotation und den Wert der Variablen per Introspektion zu ermitteln und diese nach dem Variablennamen anzuzeigen. Um dies zu überschreiben, kann ein benutzerdefinierter String für den Wert der Variablen als Argument für annotation verwendet werden.

Wenn beispielsweise der Laufzeitwert von FILE_MODE 0o755 ist, wird der angezeigte Wert 493 sein (da oct(493) == '0o755'). Dies kann durch Setzen von :annotation: = 0o755 behoben werden.

Wenn :annotation: ohne Argumente verwendet wird, wird für die Variable kein Wert oder kein Typ-Hinweis angezeigt.

:no-value:

Hinzugefügt in Version 3.4.

Um den Typ-Hinweis der Variable ohne Wert anzuzeigen, verwenden Sie die Option :no-value:. Wenn sowohl die Option :annotation: als auch :no-value: verwendet werden, hat :no-value: keine Auswirkung.

Automatische Dokumentation von Typ-Aliassen

.. autotype::

Hinzugefügt in Version 9.0.

Dokumentiert einen Typ-Alias auf Modulebene (Anweisung type), der auf PEP 695 basiert. Standardmäßig fügt die Direktive nur den Docstring des Alias selbst ein.

Die Direktive kann auch eigenen Inhalt enthalten, der in den resultierenden Nicht-Auto-Direktiven-Quellcode nach dem Docstring (aber vor jeder automatischen Mitgliedsdokumentation) eingefügt wird.

Daher können Sie auch automatische und nicht-automatische Member-Dokumentation mischen.

Optionen

:no-index:

Erzeugt keinen Indexeintrag für die dokumentierte Klasse oder für automatisch dokumentierte Mitglieder.

:no-index-entry:

Erzeugt keinen Indexeintrag für die dokumentierte Klasse oder für automatisch dokumentierte Mitglieder. Im Gegensatz zu :no-index: werden Querverweise weiterhin erstellt.

Konfiguration

Es gibt auch Konfigurationswerte, die Sie setzen können

autodoc_use_legacy_class_based
Typ:
bool
Standard:
False

Wenn wahr, verwendet autodoc die ältere klassenbasierte Implementierung. Dies ist das Verhalten vor Sphinx 9.0. Es basiert auf der Documenter-Klassenhierarchie.

Diese Einstellung dient der Rückwärtskompatibilität, falls Ihre Dokumentation oder eine von Ihnen verwendete Erweiterung die ältere klassenbasierte API im Python-Code verwendet oder monkeypatched. In diesem Fall setzen Sie autodoc_use_legacy_class_based = True in Ihrer conf.py. Fügen Sie bitte auch einen Kommentar zu dem Tracking-Issue auf GitHub hinzu, damit die Maintainer über Ihren Anwendungsfall informiert sind und möglicherweise zukünftige Verbesserungen vornehmen können.

Hinweis

Die ältere klassenbasierte Implementierung unterstützt keine PEP 695-Typ-Aliasse.

autoclass_content
Typ:
str
Standard:
'class'

Dieser Wert wählt aus, welcher Inhalt in den Hauptteil einer autoclass-Direktive eingefügt wird. Mögliche Werte sind:

'class'

Nur der Docstring der Klasse wird eingefügt. Sie können __init__ weiterhin als separate Methode mit automethod oder der Option members für autoclass dokumentieren.

'both'

Der Docstring der Klasse und der Docstring der Methode __init__ werden verkettet und eingefügt.

'init'

Nur der Docstring der Methode __init__ wird eingefügt.

Hinzugefügt in Version 0.3.

Wenn die Klasse keine __init__-Methode hat oder der Docstring der __init__-Methode leer ist, aber die Klasse eine __new__-Methode mit einem Docstring hat, wird dieser stattdessen verwendet.

Hinzugefügt in Version 1.4.

autodoc_class_signature
Typ:
str
Standard:
'mixed'

Dieser Wert wählt aus, wie die Signatur für die Klasse angezeigt wird, die von der autoclass-Direktive definiert wird. Mögliche Werte sind:

'mixed'

Anzeige der Signatur mit dem Klassennamen.

'separated'

Anzeige der Signatur als Methode.

Hinzugefügt in Version 4.1.

autodoc_member_order
Typ:
str
Standard:
'alphabetical'

Definiert die Reihenfolge, in der Mitglieder von automodule und autoclass aufgelistet werden. Unterstützte Werte sind:

  • 'alphabetical': Alphabetische Reihenfolge.

  • 'groupwise': Reihenfolge nach Mitgliedstyp. Die Reihenfolge ist:

    • für Module, Ausnahmen, Klassen, Funktionen, Daten

    • für Klassen: Klassenmethoden, statische Methoden, Methoden,

      und Eigenschaften/Attribute

    Mitglieder werden innerhalb der Gruppen alphabetisch sortiert.

  • 'bysource': Reihenfolge, in der die Mitglieder im Quellcode erscheinen. Dies erfordert, dass das Modul ein Python-Modul mit verfügbarem Quellcode ist.

Hinzugefügt in Version 0.6.

Geändert in Version 1.0: Unterstützung für 'bysource'.

autodoc_default_options
Typ:
dict[str, str | bool]
Standard:
{}

Die Standardoptionen für autodoc-Direktiven. Sie werden automatisch auf alle autodoc-Direktiven angewendet. Es muss ein Dictionary sein, das Optionsnamen auf Werte abbildet. Zum Beispiel:

autodoc_default_options = {
    'members': 'var1, var2',
    'member-order': 'bysource',
    'special-members': '__init__',
    'undoc-members': True,
    'exclude-members': '__weakref__'
}

Das Setzen von None oder True auf den Wert entspricht der Angabe nur des Optionsnamens bei den Direktiven.

Die unterstützten Optionen sind:

Hinzugefügt in Version 1.8.

Geändert in Version 2.0: Akzeptiert True als Wert.

Geändert in Version 2.1: 'imported-members' hinzugefügt.

Geändert in Version 4.1: 'class-doc-from' hinzugefügt.

Geändert in Version 4.5: 'no-value' hinzugefügt.

autodoc_docstring_signature
Typ:
bool
Standard:
True

Von C-Modulen importierte Funktionen können nicht introspektiert werden, daher kann die Signatur solcher Funktionen nicht automatisch ermittelt werden. Es ist jedoch eine gängige Konvention, die Signatur in die erste Zeile des Docstrings der Funktion zu setzen.

Wenn dieser boolesche Wert auf True gesetzt ist (was der Standard ist), prüft autodoc die erste Zeile des Docstrings für Funktionen und Methoden. Wenn diese wie eine Signatur aussieht, wird die Zeile als Signatur verwendet und aus dem Docstring-Inhalt entfernt.

autodoc sucht weiterhin nach mehreren Signaturzeilen und stoppt bei der ersten Zeile, die nicht wie eine Signatur aussieht. Dies ist nützlich für die Deklaration von überladenen Funktionssignaturen.

Hinzugefügt in Version 1.1.

Geändert in Version 3.1: Unterstützung für überladene Signaturen.

Geändert in Version 4.0: Überladene Signaturen müssen nicht durch einen Backslash getrennt sein.

autodoc_mock_imports
Typ:
list[str]
Standard:
[]

Dieser Wert enthält eine Liste von Modulen, die gemockt werden sollen. Dies ist nützlich, wenn einige externe Abhängigkeiten zur Build-Zeit nicht erfüllt sind und den Build-Prozess unterbrechen. Sie können nur das Root-Paket der Abhängigkeiten selbst angeben und die Untermodule weglassen.

autodoc_mock_imports = ['django']

Mockt alle Imports unter dem django-Paket.

Hinzugefügt in Version 1.3.

Geändert in Version 1.6: Dieser Konfigurationswert erfordert nur die Deklaration der Top-Level-Module, die gemockt werden sollen.

autodoc_typehints
Typ:
str
Standard:
'signature'

Dieser Wert steuert, wie Typ-Hints dargestellt werden. Die Einstellung nimmt folgende Werte an:

  • 'signature' – Zeigt Typ-Hints in der Signatur an.

  • 'description' – Zeigt Typ-Hints als Inhalt der Funktion oder Methode an. Die Typ-Hints von überladenen Funktionen oder Methoden werden weiterhin in der Signatur dargestellt.

  • 'none' – Zeigt keine Typ-Hints an.

  • 'both' – Zeigt Typ-Hints sowohl in der Signatur als auch als Inhalt der Funktion oder Methode an.

Überladene Funktionen oder Methoden werden keine Typ-Hints in der Beschreibung enthalten, da es unmöglich ist, alle möglichen Überladungen als Parameterliste genau darzustellen.

Hinzugefügt in Version 2.1.

Hinzugefügt in Version 3.0: Neue Option 'description' hinzugefügt.

Hinzugefügt in Version 4.1: Neue Option 'both' hinzugefügt.

autodoc_typehints_description_target
Typ:
str
Standard:
'all'

Dieser Wert steuert, ob die Typen von undokumentierten Parametern und Rückgabewerten dokumentiert werden, wenn autodoc_typehints auf 'description' gesetzt ist. Unterstützte Werte:

  • 'all': Typen werden für alle Parameter und Rückgabewerte dokumentiert, unabhängig davon, ob sie bereits dokumentiert sind oder nicht.

  • 'documented': Typen werden nur für einen Parameter oder einen Rückgabewert dokumentiert, der bereits durch den Docstring dokumentiert ist.

  • 'documented_params': Parametertypen werden nur dann annotiert, wenn der Parameter im Docstring dokumentiert ist. Der Rückgabetyp wird immer annotiert (außer wenn er None ist).

Hinzugefügt in Version 4.0.

Hinzugefügt in Version 5.0: Neue Option 'documented_params' hinzugefügt.

autodoc_type_aliases
Typ:
dict[str, str]
Standard:
{}

Ein Dictionary für benutzerdefinierte Typ-Aliasse, das einen Typnamen auf den vollständig qualifizierten Objektnamen abbildet. Es wird verwendet, um Typ-Aliasse, die im Dokument nicht ausgewertet wurden, beizubehalten.

Die Typ-Aliasse sind nur verfügbar, wenn Ihr Programm die verzögerte Auswertung von Annotationen (PEP 563)-Funktion über from __future__ import annotations aktiviert.

Zum Beispiel gibt es Code, der einen Typ-Alias verwendet:

from __future__ import annotations

AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

def f() -> AliasType:
    ...

Wenn autodoc_type_aliases nicht gesetzt ist, generiert autodoc intern folgenden Markup aus diesem Code:

.. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]

   ...

Wenn Sie autodoc_type_aliases als {'AliasType': 'your.module.AliasType'} setzen, generiert es intern folgende Dokumentation:

.. py:function:: f() -> your.module.AliasType:

   ...

Hinzugefügt in Version 3.3.

autodoc_typehints_format
Typ:
str
Standard:
'short'

Dieser Wert steuert das Format von Typ-Hints. Die Einstellung nimmt folgende Werte an:

  • 'fully-qualified' – Zeigt den Modulnamen und seinen Namen von Typ-Hints an.

  • 'short' – Unterdrückt die führenden Modulnamen der Typ-Hints (z.B. io.StringIO -> StringIO).

Hinzugefügt in Version 4.4.

Geändert in Version 5.0: Die Standardeinstellung wurde auf 'short' geändert.

autodoc_preserve_defaults
Typ:
bool
Standard:
False

Wenn True, werden die Standardargumentwerte von Funktionen bei der Dokumentationsgenerierung nicht ausgewertet. Sie werden so im Quellcode belassen, wie sie sind.

Hinzugefügt in Version 4.0: Als experimentelle Funktion hinzugefügt. Dies wird zukünftig in den autodoc-Kern integriert.

autodoc_use_type_comments
Typ:
bool
Standard:
True

Versucht, # type: ... Kommentare aus dem Quellcode zu lesen, um fehlende Typ-Annotationen zu ergänzen, wenn True.

Dies kann deaktiviert werden, wenn Ihr Quellcode keine Typ-Kommentare verwendet, z. B. wenn er ausschließlich Typ-Annotationen verwendet oder keine Typ-Hints jeglicher Art.

Hinzugefügt in Version 8.2: Option hinzugefügt, um die Verwendung von Typ-Kommentaren über die neue Option autodoc_use_type_comments zu deaktivieren, die standardmäßig auf True gesetzt ist (aus Kompatibilitätsgründen). Der Standardwert wird in Sphinx 10 auf False geändert.

autodoc_warningiserror
Typ:
bool
Standard:
True

Dieser Wert steuert das Verhalten von sphinx-build --fail-on-warning beim Importieren von Modulen. Wenn False angegeben wird, unterdrückt autodoc erzwungen den Fehler, wenn das importierte Modul Warnungen ausgibt.

Geändert in Version 8.1: Diese Option hat keine Wirkung mehr, da --fail-on-warning nicht mehr frühzeitig beendet.

autodoc_inherit_docstrings
Typ:
bool
Standard:
True

Dieser Wert steuert die Vererbung von Docstrings. Wenn auf True gesetzt, wird der Docstring für Klassen oder Methoden, falls nicht explizit gesetzt, von den Eltern geerbt.

Hinzugefügt in Version 1.7.

suppress_warnings
Typ:
Sequenz[str]
Standard:
()

autodoc unterstützt das Unterdrücken von Warnmeldungen über suppress_warnings. Es definiert die folgenden zusätzlichen Warnungstypen:

  • autodoc

  • autodoc.import_object

Docstring-Vorverarbeitung

autodoc bietet die folgenden zusätzlichen Ereignisse:

autodoc-process-docstring(app, obj_type, name, obj, options, lines)

Hinzugefügt in Version 0.4.

Ausgelöst, wenn autodoc einen Docstring gelesen und verarbeitet hat. *lines* ist eine Liste von Strings – die Zeilen des verarbeiteten Docstrings –, die der Ereignisbehandler **in-place** ändern kann, um zu ändern, was Sphinx in die Ausgabe schreibt.

Parameter:

  • app – das Sphinx-Anwendungsobjekt

  • obj_type – der Typ des Objekts, zu dem der Docstring gehört (einer von 'module', 'class', 'exception', 'function', 'decorator', 'method', 'property', 'attribute', 'data' oder 'type')

  • name – der vollständig qualifizierte Name des Objekts

  • obj – das Objekt selbst

  • options – die Optionen, die an die Direktive übergeben wurden: ein Objekt mit den Attributen inherited_members, undoc_members, show_inheritance und no-index, die wahr sind, wenn das gleichnamige Flag bei der Auto-Direktive gegeben wurde.

  • lines – die Zeilen des Docstrings, siehe oben

autodoc-before-process-signature(app, obj, bound_method)

Hinzugefügt in Version 2.4.

Ausgelöst, bevor autodoc eine Signatur für ein Objekt formatiert. Der Ereignisbehandler kann ein Objekt ändern, um seine Signatur zu ändern.

Parameter:

  • app – das Sphinx-Anwendungsobjekt

  • obj – das Objekt selbst

  • bound_method – ein boolescher Wert, der angibt, ob ein Objekt eine gebundene Methode ist oder nicht.

autodoc-process-signature(app, obj_type, name, obj, options, signature, return_annotation)

Hinzugefügt in Version 0.5.

Ausgelöst, wenn autodoc eine Signatur für ein Objekt formatiert hat. Der Ereignisbehandler kann ein neues Tupel (signature, return_annotation) zurückgeben, um zu ändern, was Sphinx in die Ausgabe schreibt.

Parameter:

  • app – das Sphinx-Anwendungsobjekt

  • obj_type – der Typ des Objekts, zu dem der Docstring gehört (einer von 'module', 'class', 'exception', 'function', 'decorator', 'method', 'property', 'attribute', 'data' oder 'type')

  • name – der vollständig qualifizierte Name des Objekts

  • obj – das Objekt selbst

  • options – die Optionen, die an die Direktive übergeben wurden: ein Objekt mit den Attributen inherited_members, undoc_members, show_inheritance und no-index, die wahr sind, wenn das gleichnamige Flag bei der Auto-Direktive gegeben wurde.

  • signature – Funktionssignatur, als String im Format '(parameter_1, parameter_2)' oder None, wenn die Introspektion nicht erfolgreich war und die Signatur nicht in der Direktive angegeben wurde.

  • return_annotation – Rückgabe-Annotation der Funktion als String im Format 'annotation' oder '', wenn keine Rückgabe-Annotation vorhanden ist.

Das Modul sphinx.ext.autodoc stellt Factory-Funktionen für häufig benötigte Docstring-Verarbeitungen im Ereignis autodoc-process-docstring bereit.

sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: Sequence[str] | None = None) → _AutodocProcessDocstringListener[source]

Gibt einen Listener zurück, der die ersten *pre* und die letzten *post* Zeilen jedes Docstrings entfernt. Wenn *what* eine Sequenz von Strings ist, werden nur Docstrings eines Typs in *what* verarbeitet.

Verwenden Sie es wie folgt (z. B. in der setup()-Funktion von conf.py):

from sphinx.ext.autodoc import cut_lines

app.connect('autodoc-process-docstring', cut_lines(4, what={'module'}))

Dies kann (und sollte) anstelle von automodule_skip_lines verwendet werden.

sphinx.ext.autodoc.between(marker: str, what: Sequence[str] | None = None, keepempty: bool = False, exclude: bool = False) → _AutodocProcessDocstringListener[source]

Gibt einen Listener zurück, der Zeilen zwischen Zeilen, die dem regulären Ausdruck des Markers entsprechen, entweder beibehält oder, wenn exclude True ist, ausschließt. Wenn keine Zeile übereinstimmt, wäre der resultierende Docstring leer, daher wird keine Änderung vorgenommen, es sei denn, keepempty ist wahr.

Wenn what eine Zeichenkette ist, werden nur Docstrings eines Typs in what verarbeitet.

autodoc-process-bases(app, name, obj, _unused, bases)

Wird ausgelöst, wenn autodoc eine Klasse gelesen und verarbeitet hat, um die Basisklassen zu ermitteln. bases ist eine Liste von Klassen, die der Event-Handler in place ändern kann, um zu ändern, was Sphinx in die Ausgabe einfügt. Sie wird nur ausgelöst, wenn die Option show-inheritance angegeben ist.

Parameter:

  • app – das Sphinx-Anwendungsobjekt

  • name – der vollständig qualifizierte Name des Objekts

  • obj – das Objekt selbst

  • _unused – ungenutzter Platzhalter

  • bases – die Liste der Basisklassen-Signatur. siehe oben.

Hinzugefügt in Version 4.1.

Changed in version 4.3: bases kann einen String als Basisklassennamen enthalten. Er wird als reStructuredText verarbeitet.

Mitglieder überspringen

autodoc erlaubt dem Benutzer, eine benutzerdefinierte Methode zur Bestimmung, ob ein Mitglied in die Dokumentation aufgenommen werden soll, zu definieren, indem er das folgende Ereignis verwendet

autodoc-skip-member(app, obj_type, name, obj, skip, options)

Hinzugefügt in Version 0.5.

Wird ausgelöst, wenn autodoc entscheiden muss, ob ein Mitglied in die Dokumentation aufgenommen werden soll. Das Mitglied wird ausgeschlossen, wenn ein Handler True zurückgibt. Es wird aufgenommen, wenn der Handler False zurückgibt.

Wenn mehr als eine aktivierte Erweiterung das Ereignis autodoc-skip-member behandelt, verwendet autodoc den ersten Nicht-None-Wert, der von einem Handler zurückgegeben wird. Handler sollten None zurückgeben, um auf das Überspringungsverhalten von autodoc und anderen aktivierten Erweiterungen zurückzufallen.

Parameter:

  • app – das Sphinx-Anwendungsobjekt

  • obj_type – der Typ des Objekts, zu dem der Docstring gehört (einer von 'module', 'class', 'exception', 'function', 'decorator', 'method', 'property', 'attribute', 'data' oder 'type')

  • name – der vollständig qualifizierte Name des Objekts

  • obj – das Objekt selbst

  • skip – ein boolescher Wert, der angibt, ob autodoc dieses Mitglied überspringen wird, wenn der benutzerdefinierte Handler die Entscheidung nicht überschreibt

  • options – die Optionen, die an die Direktive übergeben wurden: ein Objekt mit den Attributen inherited_members, undoc_members, show_inheritance und no-index, die wahr sind, wenn das gleichnamige Flag bei der Auto-Direktive gegeben wurde.