sphinx-apidoc

Zusammenfassung

sphinx-apidoc [OPTIONEN] -o <AUSGABEVERZEICHNIS> <MODULPFAD> [AUSSCHLUSS_MUSTER …]

Beschreibung

sphinx-apidoc ist ein Werkzeug zur automatischen Generierung von Sphinx-Quellen, das mittels der autodoc-Erweiterung ein ganzes Paket im Stil anderer automatischer API-Dokumentationstools dokumentiert.

MODULPFAD ist der Pfad zu einem Python-Paket, das dokumentiert werden soll, und AUSGABEVERZEICHNIS ist das Verzeichnis, in dem die generierten Quellen abgelegt werden. Alle angegebenen AUSSCHLUSS_MUSTERN sind fnmatch-Stil Datei- und/oder Verzeichnismuster, die von der Generierung ausgeschlossen werden.

Warnung

sphinx-apidoc generiert Quelldateien, die sphinx.ext.autodoc zur Dokumentation aller gefundenen Module verwenden. Wenn Module Nebeneffekte beim Import 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.

Optionen

-o <AUSGABEVERZEICHNIS>

Verzeichnis zum Ablegen der Ausgabedateien. Wenn es nicht existiert, wird es erstellt.

-q

Gib nichts auf der Standardausgabe aus, schreibe nur Warnungen und Fehler auf die Standardfehlerausgabe.

-f, --force

Erzwinge das Überschreiben aller vorhandenen generierten Dateien.

-l, --follow-links

Symbolische Links verfolgen. Standardmäßig auf False gesetzt.

-n, --dry-run

Keine Dateien erstellen oder löschen.

-s <suffix>

Suffix für die generierten Quelldateien. Standardmäßig auf rst gesetzt.

-d <MAXDEPTH>

Maximale Tiefe für die generierte Inhaltsverzeichniss-Datei. Standardmäßig auf 4 gesetzt.

--tocfile

Dateiname für eine Inhaltsverzeichniss-Datei. Standardmäßig auf modules gesetzt.

-T, --no-toc

Erstelle keine Inhaltsverzeichniss-Datei. Wird ignoriert, wenn --full angegeben ist.

--remove-old

Entferne vorhandene Dateien im Ausgabeverzeichnis, die nicht mehr generiert werden. Nicht kompatibel mit --full.

-F, --full

Generiere ein vollständiges Sphinx-Projekt (conf.py, Makefile etc.) unter Verwendung desselben Mechanismus wie sphinx-quickstart.

-e, --separate

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

Hinzugefügt in Version 1.2.

-E, --no-headings

Keine Überschriften für die Module/Pakete erstellen. Dies ist nützlich, zum Beispiel, wenn Docstrings bereits Überschriften enthalten.

-P, --private

"_private" Module einschließen.

Hinzugefügt in Version 1.2.

--implicit-namespaces

Ohne diese Option sucht sphinx-apidoc in sys.path nach Python-Paketen, die __init__.py-Dateien enthalten, oder nach einzelnen Python-Modulen.

Diese Option verwendet stattdessen PEP 420 implizite Namespaces, die Pfadlayouts wie foo/bar/module.py oder foo/bar/baz/__init__.py erlauben (beachten Sie, dass bar und foo Namespaces und keine Module sind).

-M, --module-first

Moduldokumentation vor Untermoduldokumentation platzieren.

Diese Optionen werden verwendet, wenn --full angegeben ist

-a

module_path zu sys.path hinzufügen.

-H <projekt>

Setzt den Projektnamen, der in generierte Dateien eingefügt werden soll (siehe project).

-A <autor>

Setzt den oder die Autorennamen, die in generierte Dateien eingefügt werden sollen (siehe copyright).

-V <version>

Setzt die Projektversion, die in generierte Dateien eingefügt werden soll (siehe version).

-R <release>

Setzt den Projekt-Release, der in generierte Dateien eingefügt werden soll (siehe release).

Projekt-Templating

Hinzugefügt in Version 2.2: Projekt-Templating-Optionen für sphinx-apidoc

-t, --templatedir=TEMPLATEDIR

Template-Verzeichnis für Template-Dateien. Sie können die Templates der von apidoc generierten Sphinx-Projektdaten modifizieren. Folgende Jinja2-Template-Dateien sind zulässig

  • module.rst.jinja

  • package.rst.jinja

  • toc.rst.jinja

  • root_doc.rst.jinja

  • conf.py.jinja

  • Makefile.jinja

  • Makefile.new.jinja

  • make.bat.jinja

  • make.bat.new.jinja

Im Detail finden Sie die System-Template-Dateien, die Sphinx bereitstellt. (sphinx/templates/apidoc und sphinx/templates/quickstart)

Umgebung

SPHINX_APIDOC_OPTIONS

Eine durch Kommas getrennte Liste von Optionen, die an generierte automodule-Direktiven angehängt werden. Standardmäßig members,undoc-members,show-inheritance.

Siehe auch

sphinx-build(1), sphinx-autogen(1)