Eine Codebasis dokumentieren¶
Ein öffentlicher Name braucht einen Vertrag. Erklären Sie Eingabe, Ergebnis, Eigentümerschaft und Fehlerbedingungen. Eine Signatur allein ist kein Handbuch.
Odin¶
odin_autoapi_dirs = ["../../lib"]
odin_autoapi_root = "api"
odin_autoapi_options = ["members", "undoc-members"]
Guidedog liest Odin-Quelltext mit dem Odin-Parser. Das dokumentierte Paket wird weder kompiliert noch ausgeführt. Generierte Seiten werden Teil des Dokumentgraphen und Objektinventars. Das getrennte API-Projekt liegt in docs/api. Direktiven, Signaturen und Optionen stehen in Odin dokumentieren.
Python¶
extensions = ["sphinx.ext.autodoc"]
autodoc_source_paths = ["../src"]
Guidedog parst Python-Quelltext, statt ihn zu importieren. Das vermeidet Import-Nebenwirkungen. Zur Laufzeit erzeugte Objekte können jedoch fehlen. Beschreiben Sie diese ausdrücklich, falls sie zur öffentlichen Schnittstelle gehören. Die genauen Erkennungsregeln stehen in Python mit autodoc dokumentieren.
Projekte verknüpfen¶
Veröffentlichen Sie das erzeugte objects.inv mit der Website. Andere Projekte können Namen dann über intersphinx-Zuordnungen auflösen. Verwenden Sie für reproduzierbare Builds explizite Zuordnungen. Siehe Auf andere Projekte verweisen.