sphinx.ext.autosummary – Generieren von Autodoc-Zusammenfassungen

Hinzugefügt in Version 0.6.

Diese Erweiterung generiert Listen von Funktions-/Methoden-/Attributzusammenfassungen, ähnlich denen, die z. B. von Epydoc und anderen API-Dokumentationsgeneratoren ausgegeben werden. Dies ist besonders nützlich, wenn Ihre Docstrings lang und detailliert sind und es einfacher zu lesen ist, jeden davon auf einer separaten Seite anzuzeigen.

Die Erweiterung sphinx.ext.autosummary erledigt dies in zwei Teilen

  1. Es gibt eine autosummary-Direktive zum Generieren von Zusammenfassungslisten, die Links zu den dokumentierten Elementen und kurze Zusammenfassungs-Teaser aus ihren Docstrings enthalten.

  2. Eine autosummary-Direktive generiert auch kurze „Stub“-Dateien für die in ihrem Inhalt aufgeführten Einträge. Diese Dateien enthalten standardmäßig nur die entsprechende sphinx.ext.autodoc-Direktive, können aber mit Vorlagen angepasst werden.

    Das Skript sphinx-autogen kann Stub-Dateien auch von der Befehlszeile aus generieren.

.. autosummary::

Fügt eine Tabelle ein, die Links zu dokumentierten Elementen und eine kurze Zusammenfassung (erster Satz des Docstrings) für jedes davon enthält.

Die autosummary-Direktive kann auch optional als toctree-Eintrag für die enthaltenen Elemente dienen. Optional können auch Stub- .rst-Dateien für diese Elemente automatisch generiert werden, wenn autosummary_generate auf True gesetzt ist.

Zum Beispiel,

.. currentmodule:: sphinx

.. autosummary::

   environment.BuildEnvironment
   util.relative_uri

erzeugt eine Tabelle wie diese

environment.BuildEnvironment(app)

Die Umgebung, in der die ReST-Dateien übersetzt werden.

util.relative_uri(base, to)

Gibt eine relative URL von base nach to zurück.

Autosummary verarbeitet die Docstrings und Signaturen mit denselben autodoc-process-docstring- und autodoc-process-signature-Hooks wie autodoc.

Optionen

:class: Klassennamen (eine Liste von Klassennamen, durch Leerzeichen getrennt)

Weist der Tabelle Klassenattribute zu. Dies ist eine häufige Option.

Hinzugefügt in Version 8.2.

:toctree: optionaler Verzeichnisname

Wenn Sie möchten, dass die autosummary-Tabelle auch als toctree-Eintrag dient, verwenden Sie die Option toctree, zum Beispiel

.. autosummary::
   :toctree: DIRNAME

   sphinx.environment.BuildEnvironment
   sphinx.util.relative_uri

Die Option toctree signalisiert auch dem Skript sphinx-autogen, dass für die in dieser Direktive aufgeführten Einträge Stub-Seiten generiert werden sollen. Die Option akzeptiert einen Verzeichnisnamen als Argument; sphinx-autogen wird seine Ausgabe standardmäßig in diesem Verzeichnis platzieren. Wenn kein Argument angegeben wird, wird die Ausgabe im selben Verzeichnis wie die Datei platziert, die die Direktive enthält.

Hinzugefügt in Version 0.6.

:caption: Caption des ToC

Fügt dem Toctree eine Beschriftung hinzu.

Hinzugefügt in Version 3.1.

:signatures: Format

Wie Signaturen angezeigt werden sollen. Gültige Werte sind

  • long (Standard): verwendet eine lange Signatur. Diese wird immer noch abgeschnitten, damit Name plus Signatur eine bestimmte Länge nicht überschreiten.

  • short: Funktions- und Klassensignaturen werden als (…) angezeigt, wenn sie Argumente haben, und als (), wenn sie keine Argumente haben.

  • none: Signaturen nicht anzeigen.

Hinzugefügt in Version 8.2.

:nosignatures:

Zeigt keine Funktionssignaturen in der Zusammenfassung an.

Dies ist gleichbedeutend mit :signatures: none.

Hinzugefügt in Version 0.6.

Geändert in Version 8.2: Die Direktivenoption wird durch die allgemeinere Option :signatures: none ersetzt.

Sie wird in einer zukünftigen Version von Sphinx veraltet und entfernt.

:template: Dateiname

Gibt eine benutzerdefinierte Vorlage für die Darstellung der Zusammenfassung an. Zum Beispiel,

.. autosummary::
   :template: mytemplate.rst

   sphinx.environment.BuildEnvironment

würde die Vorlage mytemplate.rst in Ihrem templates_path verwenden, um die Seiten für alle aufgeführten Einträge zu generieren. Siehe Anpassen von Vorlagen unten.

Hinzugefügt in Version 1.0.

:recursive:

Generiert Dokumente für Module und Unterpakete rekursiv. Zum Beispiel,

.. autosummary::
   :recursive:

   sphinx.environment.BuildEnvironment

Hinzugefügt in Version 3.1.

sphinx-autogen – Generiert Autodoc-Stub-Seiten

Das Skript sphinx-autogen kann verwendet werden, um bequem Stub-Dokumentationsseiten für Elemente zu generieren, die in autosummary-Listen enthalten sind.

Zum Beispiel der Befehl

$ sphinx-autogen -o generated *.rst

liest alle autosummary-Tabellen in den *.rst-Dateien, die die Option :toctree: gesetzt haben, und gibt entsprechende Stub-Seiten im Verzeichnis generated für alle dokumentierten Elemente aus. Die generierten Seiten enthalten standardmäßig Text der Form

sphinx.util.relative_uri
========================

.. autofunction:: sphinx.util.relative_uri

Wenn die Option -o nicht angegeben wird, platziert das Skript die Ausgabedateien in den Verzeichnissen, die in den :toctree:-Optionen angegeben sind.

Weitere Informationen finden Sie in der sphinx-autogen-Dokumentation

Generieren von Stub-Seiten automatisch

Wenn Sie keine Stub-Seiten mit sphinx-autogen erstellen möchten, können Sie auch diese Konfigurationswerte verwenden

autosummary_context
Typ:
dict[str, Any]
Standard:
{}

Ein Wörterbuch mit Werten, die an den Kontext der Vorlagen-Engine für Autosummary-Stub-Dateien übergeben werden.

Hinzugefügt in Version 3.1.

autosummary_generate
Typ:
bool
Standard:
True

Boolescher Wert, der angibt, ob alle gefundenen Dokumente nach Autosummary-Direktiven durchsucht und für jede Stub-Seiten generiert werden sollen.

Kann auch eine Liste von Dokumenten sein, für die Stub-Seiten generiert werden sollen.

Die neuen Dateien werden in den Verzeichnissen platziert, die in den :toctree:-Optionen der Direktiven angegeben sind.

Geändert in Version 2.3: Löst das autodoc-skip-member-Ereignis aus, wie autodoc es tut.

Geändert in Version 4.0: Standardmäßig aktiviert.

autosummary_generate_overwrite
Typ:
bool
Standard:
True

Wenn True, überschreibt Autosummary vorhandene Dateien mit generierten Stub-Seiten.

Hinzugefügt in Version 3.0.

autosummary_mock_imports
Typ:
list[str]
Standard:
[]

Dieser Wert enthält eine Liste von Modulen, die gemockt werden sollen. Siehe autodoc_mock_imports für weitere Details. Standardmäßig wird autodoc_mock_imports verwendet.

Hinzugefügt in Version 2.0.

autosummary_imported_members
Typ:
bool
Standard:
False

Ein boolesches Flag, das angibt, ob importierte Klassen und Funktionen in Modulen dokumentiert werden sollen.

Hinzugefügt in Version 2.1.

Geändert in Version 4.4: Wenn autosummary_ignore_module_all False ist, wird dieser Konfigurationswert für Mitglieder, die in __all__ aufgeführt sind, ignoriert.

autosummary_ignore_module_all
Typ:
bool
Standard:
True

Wenn False und ein Modul das Attribut __all__ gesetzt hat, dokumentiert Autosummary jedes Mitglied, das in __all__ aufgeführt ist, und keine anderen.

Beachten Sie, dass, wenn ein importiertes Mitglied in __all__ aufgeführt ist, es unabhängig vom Wert von autosummary_imported_members dokumentiert wird. Um das Verhalten von from module import * zu emulieren, setzen Sie autosummary_ignore_module_all auf False und autosummary_imported_members auf True.

Hinzugefügt in Version 4.4.

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

Ein Wörterbuch, das Objekt-Namen auf Dateinamen abbildet. Dies ist notwendig, um Namenskonflikte zu vermeiden, bei denen mehrere Objekte Namen haben, die auf Dateisystemen, auf denen Dateinamen nicht zwischen Groß- und Kleinschreibung unterscheiden, bei Ignorierung der Groß-/Kleinschreibung nicht unterscheidbar sind.

Hinzugefügt in Version 3.2.

Anpassen von Vorlagen

Hinzugefügt in Version 1.0.

Sie können die Stub-Seiten-Vorlagen ähnlich wie die HTML-Jinja-Vorlagen anpassen. Siehe Templating. (TemplateBridge wird nicht unterstützt.)

Hinweis

Wenn Sie viel Zeit mit der Anpassung der Stub-Vorlagen verbringen, kann dies darauf hindeuten, dass es besser ist, benutzerdefinierte narrative Dokumentation zu schreiben.

Autosummary verwendet die folgenden Jinja-Vorlagendateien

  • autosummary/base.rst – Fallback-Vorlage

  • autosummary/module.rst – Vorlage für Module

  • autosummary/class.rst – Vorlage für Klassen

  • autosummary/function.rst – Vorlage für Funktionen

  • autosummary/attribute.rst – Vorlage für Klassenattribute

  • autosummary/method.rst – Vorlage für Klassenmethoden

Die folgenden Variablen sind in den Vorlagen verfügbar

name

Name des dokumentierten Objekts, ohne Modul- und Klassenteile.

objname

Name des dokumentierten Objekts, ohne Modulteile.

fullname

Vollständiger Name des dokumentierten Objekts, einschließlich Modul- und Klassenteile.

objtype

Typ des dokumentierten Objekts, einer davon: "module", "function", "class", "method", "attribute", "data", "object", "exception", "newvarattribute", "newtypedata", "property".

module

Name des Moduls, zu dem das dokumentierte Objekt gehört.

class

Name der Klasse, zu der das dokumentierte Objekt gehört. Nur verfügbar für Methoden und Attribute.

underline

Eine Zeichenkette, die len(full_name) * '=' enthält. Verwenden Sie stattdessen den underline-Filter.

members

Liste mit den Namen aller Mitglieder des Moduls oder der Klasse. Nur verfügbar für Module und Klassen.

inherited_members

Liste mit den Namen aller geerbten Mitglieder der Klasse. Nur verfügbar für Klassen.

Hinzugefügt in Version 1.8.0.

functions

Liste mit den Namen von „öffentlichen“ Funktionen im Modul. Hier bedeutet „öffentlich“, dass der Name nicht mit einem Unterstrich beginnt. Nur verfügbar für Module.

classes

Liste mit den Namen von „öffentlichen“ Klassen im Modul. Nur verfügbar für Module.

exceptions

Liste mit den Namen von „öffentlichen“ Ausnahmen im Modul. Nur verfügbar für Module.

methods

Liste mit den Namen von „öffentlichen“ Methoden in der Klasse. Nur verfügbar für Klassen.

attributes

Liste mit den Namen von „öffentlichen“ Attributen in der Klasse/dem Modul. Nur verfügbar für Klassen und Module.

Geändert in Version 3.1: Attribute von Modulen werden unterstützt.

modules

Liste mit den Namen von „öffentlichen“ Modulen im Paket. Nur verfügbar für Module, die Pakete sind und die Option recursive aktiviert ist.

Hinzugefügt in Version 3.1.

Zusätzlich sind die folgenden Filter verfügbar

escape(s)

Maskiert spezielle Zeichen im Text, die in RST-Kontexten verwendet werden sollen. Dies verhindert zum Beispiel, dass Sternchen etwas fett machen. Dies ersetzt den integrierten Jinja escape filter, der HTML-Escaping durchführt.

underline(s, line='=')

Fügt einer Textpassage eine Titelunterstreichung hinzu.

Zum Beispiel sollte {{ fullname | escape | underline }} verwendet werden, um den Titel einer Seite zu erzeugen.

Hinweis

Sie können die autosummary-Direktive in den Stub-Seiten verwenden. Stub-Seiten werden auch auf Basis dieser Direktiven generiert.