sphinx.ext.apidoc – Generiert API-Dokumentation aus Python-Paketen

Hinzugefügt in Version 8.2.

sphinx.ext.apidoc ist ein Werkzeug zur automatischen Generierung von Sphinx-Quellen aus Python-Paketen. Es stellt das Kommandozeilenwerkzeug sphinx-apidoc als Erweiterung bereit, sodass es während des Sphinx-Build-Prozesses ausgeführt werden kann.

Die Erweiterung schreibt generierte Quelldateien in ein bereitgestelltes Verzeichnis, das dann von Sphinx unter Verwendung der sphinx.ext.autodoc-Erweiterung gelesen wird.

Warnung

sphinx.ext.apidoc generiert Quelldateien, die sphinx.ext.autodoc verwenden, um alle gefundenen Module zu dokumentieren. Wenn Module Import-Seiteneffekte haben, werden diese von autodoc ausgeführt, wenn sphinx-build ausgeführt wird.

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

Konfiguration

Die apidoc-Erweiterung verwendet die folgenden Konfigurationswerte

apidoc_modules
Typ:
Sequenz[dict[str, str | int | bool | Sequenz[str] | Set[str]]
Standard:
()

Eine Liste oder Sequenz von Wörterbüchern, die zu dokumentierende Module beschreiben. Wenn ein Wert in einem Wörterbuch nicht angegeben ist, wird der allgemeine Konfigurationswert als Standard verwendet.

Zum Beispiel

apidoc_modules = [
    {'path': 'path/to/module', 'destination': 'source/'},
    {
        'path': 'path/to/another_module',
        'destination': 'source/',
        'exclude_patterns': ['**/test*'],
        'max_depth': 4,
        'follow_links': False,
        'separate_modules': False,
        'include_private': False,
        'no_headings': False,
        'module_first': False,
        'implicit_namespaces': False,
        'automodule_options': {
            'members', 'show-inheritance', 'undoc-members'
        },
    },
]

Gültige Schlüssel sind

'path'

Der Pfad zum zu dokumentierenden Modul (erforderlich). Dies muss absolut oder relativ zum Konfigurationsverzeichnis sein.

'destination'

Das Ausgabeverzeichnis für generierte Dateien (erforderlich). Dies muss relativ zum Quellverzeichnis sein und wird erstellt, falls es nicht existiert.

'exclude_patterns'

Siehe apidoc_exclude_patterns.

'max_depth'

Siehe apidoc_max_depth.

'follow_links'

Siehe apidoc_follow_links.

'separate_modules'

Siehe apidoc_separate_modules.

'include_private'

Siehe apidoc_include_private.

'no_headings'

Siehe apidoc_no_headings.

'module_first'

Siehe apidoc_module_first.

'implicit_namespaces'

Siehe apidoc_implicit_namespaces.

'automodule_options'

Siehe apidoc_automodule_options.

apidoc_exclude_patterns
Typ:
Sequenz[str]
Standard:
()

Eine Sequenz von Mustern, die von der Generierung ausgeschlossen werden sollen. Dies können exakte Pfade oder fnmatch-ähnliche Muster sein.

apidoc_max_depth
Typ:
int
Standard:
4

Die maximale Tiefe der Untermodule, die im generierten Inhaltsverzeichnis angezeigt werden sollen.

Typ:
bool
Standard:
False

Symbolische Links verfolgen.

apidoc_separate_modules
Typ:
bool
Standard:
False

Dokumentation für jedes Modul auf einer einzelnen Seite platzieren.

apidoc_include_private
Typ:
bool
Standard:
False

Dokumentation für „_private“-Module mit führenden Unterstrichen generieren.

apidoc_no_headings
Typ:
bool
Standard:
False

Keine Überschriften für die Module/Pakete erstellen. Nützlich, wenn Quell-Docstrings bereits Überschriften enthalten.

apidoc_module_first
Typ:
bool
Standard:
False

Moduldokumentation vor Untermoduldokumentation platzieren.

apidoc_implicit_namespaces
Typ:
bool
Standard:
False

Standardmäßig verarbeitet sphinx-apidoc sys.path nur nach Modulen. Python 3.3 führte PEP 420 implizite Namensräume ein, die Modulpfadstrukturen wie foo/bar/module.py oder foo/bar/baz/__init__.py ermöglichen (beachten Sie, dass bar und foo Namensräume und keine Module sind).

Modulpfade mithilfe von PEP 420 impliziten Namensräumen interpretieren.

apidoc_automodule_options
Typ:
Set[str]
Standard:
{'members', 'show-inheritance', 'undoc-members'}

Optionen, die an generierte automodule-Direktiven übergeben werden.