Guidedog / Dokumentation 0.2.0

Python mit autodoc dokumentieren¶

Guidedog dokumentiert Python durch Lesen des Quelltexts. Das Paket wird nicht importiert. Docstrings und Signaturen werden Teil des Dokumentgraphen. Objekte, die erst zur Laufzeit entstehen, benötigen eine ausdrückliche Beschreibung. Diese Grenze ist bewusst gewählt.

Einrichtung¶

Tragen Sie die Erweiterung ein und geben Sie Guidedog die Paketverzeichnisse relativ zum Quellverzeichnis an, so wie sys.path sie Python mitteilt:

extensions = ["sphinx.ext.autodoc"]
autodoc_source_paths = ["../src"]

guidedog migrate erzeugt autodoc_source_paths aus den Zeilen in conf.py, die zum Paket führen, etwa sys.path.insert(0, os.path.abspath('..')). Ein anderswo installiertes Paket wird nur gefunden, wenn Sie sein Verzeichnis hinzufügen, beispielsweise einen Quelltext-Checkout einer Abhängigkeit. Guidedog durchsucht niemals Pythons eigenes site-packages.

Die Direktiven funktionieren anschließend wie in Sphinx:

.. automodule:: shop.cart
   :members:
   :show-inheritance:

.. autoclass:: shop.Cart
   :members: add, remove
   :inherited-members:

Alle Optionen von Sphinx 9.1 werden mit derselben Bedeutung unterstützt: :members:, :undoc-members:, :private-members:, :special-members:, :inherited-members:, :exclude-members:, :member-order:, :show-inheritance:, :imported-members:, :ignore-module-all:, :class-doc-from:, :no-value:, :annotation:, :no-index:, :no-index-entry:, :synopsis:, :platform:, :deprecated: sowie die no--Formen zum Aufheben von autodoc_default_options.

Einstellungen¶

Diese Einstellungen in conf.toml verwenden dieselben Namen, Werte und Standardwerte wie Sphinx.

autodoc_source_paths: Eine eigene Einstellung von Guidedog: die Verzeichnisse für Python-Module in Suchreihenfolge, relativ zum Quellverzeichnis. Es werden nur Dateien darunter gelesen. Symbolische Links, die nach außerhalb führen, werden abgewiesen.
autoclass_content: Welche Docstrings die Klasse beschreiben: "class" (Vorgabe), "init" oder "both".
autodoc_class_signature: "mixed" (Vorgabe) oder "separated"; damit wird __init__ als Methode dokumentiert.
autodoc_default_options: Eine Tabelle mit Optionen für jede Direktive, etwa members = true oder member-order = "bysource". Der Wert false lässt die Option weg.
autodoc_docstring_signature: true (Vorgabe): Eine erste Docstring-Zeile wie name(args) -> result wird als Signatur verwendet.
autodoc_inherit_docstrings: true (Vorgabe): Ein Mitglied ohne eigenen Docstring übernimmt den der Basisklasse.
autodoc_member_order: "alphabetical" (Vorgabe), "groupwise" oder "bysource".
autodoc_preserve_defaults: false (Vorgabe): Standardwerte werden wie mit repr() dargestellt. true zeigt die Schreibweise aus dem Quelltext.
autodoc_typehints: "signature" (Vorgabe), "description" (als Felder :type: und :rtype:), "both" oder "none".
autodoc_typehints_description_target: "all" (Vorgabe), "documented" oder "documented_params".
autodoc_typehints_format: "short" (Vorgabe) oder "fully-qualified".
autodoc_use_type_comments: true (Vorgabe): Kommentare mit # type: gelten als Typannotationen.
strip_signature_backslash: Verdoppelt Backslashes in Signaturen, wie Sphinx.
autodoc_mock_imports, autodoc_type_aliases, autodoc_warningiserror: Die Einstellungen werden akzeptiert. Da nichts importiert wird, sind keine Mocks nötig. Typaliase werden nicht angewendet.

Wie Guidedog das Verhalten von Python ermittelt¶

Namen werden nach den Bindungsregeln von Python aufgelöst. Mit from .app import Flask in der __init__.py eines Pakets verweist flask.Flask auf die Klasse in flask/app.py. autodoc zeigt dafür :canonical: flask.app.Flask. Basisklassen werden genauso aufgelöst. Die Methodenreihenfolge wird wie in Python berechnet; geerbte Mitglieder stammen aus dem Quelltext der Basisklassen. Namen, die nur unter if TYPE_CHECKING: importiert werden, existieren zur Laufzeit nicht. Entsprechende Annotationen bleiben daher wie in Sphinx unverändert.

Docstrings entsprechen den von Python gespeicherten Zeichenketten: Escape-Sequenzen werden ausgewertet und Einrückungen wie im Compiler von Python 3.13 entfernt. Attributdokumentation stammt aus denselben Stellen wie bei Sphinx: #:-Kommentare nach der Zuweisung oder direkt darüber sowie ein unmittelbar folgender Stringliteral. Signaturen stammen aus def. Bei Klassen werden nach Pythons Suchregeln __call__ der Metaklasse, __new__ oder __init__ verwendet; bei dataclass und NamedTuple die Felder. Varianten mit @overload ersetzen die Signatur der Implementierung.

Was sich ohne Ausführung von Python nicht feststellen lässt¶

Wenn sich Pythons Verhalten aus dem Quelltext nicht bestimmen lässt, nennt Guidedog das betroffene Objekt. Ist keine Dokumentation möglich, erscheint eine Warnung. Wird weniger als bei Sphinx dokumentiert, gibt es einen Hinweis, sichtbar mit -v.

Ein kompiliertes Modul (.so, .pyd) enthält keinen lesbaren Quelltext. Seine Objekte werden deshalb nicht gefunden.
Ein zur Laufzeit erzeugter Wert (app = Flask(__name__), now = datetime.now()) erhält kein :value:. Berechnete Standardwerte werden in ihrer Quelltextform gezeigt.
Eine Funktion, die durch einen Dekorator außerhalb der Quellpfade entsteht (@click.command()), wird als ursprüngliche Funktion dokumentiert.
Eine Klasse aus einem Paket außerhalb der Quellpfade wird nach ihrem Importpfad benannt. Dieser kann vom definierenden Modul abweichen. Mitglieder, Konstruktorsignatur und vererbbare Docstrings sind unbekannt.
Die Docstrings eingebauter Typen sind unbekannt. Eine Methode ohne eigenen Docstring, die ihn von dict erben würde, wird daher ausgelassen.
Python-Erweiterungen für autodoc-Ereignisse (autodoc-process-docstring, autodoc-skip-member usw.) werden nicht ausgeführt.
Module mit unrealistisch tiefer Verschachtelung werden mit der Warnung autodoc.too_deep nicht analysiert. Python selbst lehnt 200 verschachtelte Klammern ab. Guidedog lehnt außerdem +-Ketten mit einigen Hundert Operanden ab.
Arbeit, die sich vervielfachen kann, ist begrenzt. Die Namenssuche über Importe und Aliase endet nach 48 Schritten je Pfad und insgesamt 100,000 Schritten. Typaliase und Konstanten werden bis zu 10,000 Schritte expandiert, danach in Quelltextform gezeigt. Die MRO wird bis zu einer Tiefe von 100 Klassen verfolgt. Eine Direktive erzeugt höchstens 10,000 weitere Direktiven; darüber erscheint autodoc.limit. Diese letzte Grenze erreicht nur eine Klasse, die sich unter ihrem eigenen Namen selbst enthält.

Die meisten dieser Einschränkungen lassen sich beheben, indem die Quellverzeichnisse der fehlenden Pakete zu autodoc_source_paths hinzugefügt werden.

Erneuter Build¶

Jede von einer autodoc-Direktive gelesene Python-Datei ist eine Abhängigkeit der Seite. Nach einer Änderung wird die Seite beim nächsten Build neu gelesen. Seiten mit nicht gefundenen Objekten werden bei jedem Build erneut gelesen und erkennen das Objekt, sobald es im Quelltext vorhanden ist.

Sicherheit¶

Beim Dokumentationsbuild wird der Projektcode niemals ausgeführt. Guidedog liest Python-Quelltext als Text und verwendet dieselbe Pfadbegrenzung wie für Includes: nur unterhalb von autodoc_source_paths und ohne Links nach außerhalb.