Dies ist auf der doxygen-Website dokumentiert , aber um es hier zusammenzufassen:
Sie können doxygen verwenden, um Ihren Python-Code zu dokumentieren. Sie können entweder die Syntax der Python-Dokumentationszeichenfolge verwenden:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
In diesem Fall werden die Kommentare von doxygen extrahiert, Sie können jedoch keinen der speziellen doxygen-Befehle verwenden .
Oder Sie können (ähnlich wie bei C-Sprachen unter doxygen) den Kommentar-Marker ( #
) in der ersten Zeile vor dem Mitglied verdoppeln :
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
In diesem Fall können Sie die speziellen Sauerstoffbefehle verwenden. Es gibt keinen bestimmten Python - Ausgabemodus, aber Sie können offenbar die Ergebnisse verbessern , indem OPTMIZE_OUTPUT_JAVA
zu YES
.
Ehrlich gesagt bin ich ein wenig überrascht über den Unterschied - es scheint, als würde doxygen die Kommentare in ## Blöcken oder "" "Blöcken erkennen, der größte Teil der Arbeit wäre erledigt und Sie könnten die speziellen Befehle in verwenden Vielleicht erwarten sie, dass Leute, die "" "verwenden, sich an mehr pythonische Dokumentationspraktiken halten, und das würde die speziellen Sauerstoffbefehle stören?
Mit dem Doxypy- Eingabefilter können Sie so gut wie alle Formatierungs-Tags von Doxygen in einem Standard-Python-Dokumentzeichenfolgenformat verwenden. Ich verwende es, um ein großes gemischtes C ++ - und Python-Spielanwendungsframework zu dokumentieren, und es funktioniert gut.
quelle
Am Ende haben Sie nur zwei Möglichkeiten:
Sie generieren Ihre Inhalte mit Doxygen oder Sie generieren Ihre Inhalte mit Sphinx *.
Doxygen : Es ist nicht das Werkzeug der Wahl für die meisten Python-Projekte. Wenn Sie sich jedoch mit anderen verwandten Projekten befassen müssen, die in C oder C ++ geschrieben wurden, kann dies sinnvoll sein. Dazu können Sie die Integration zwischen Doxygen und Python mit doxypypy verbessern .
Sphinx : Das Defacto-Tool zum Dokumentieren eines Python-Projekts. Hier haben Sie drei Möglichkeiten: manuell, halbautomatisch (Stub-Generierung) und vollautomatisch (Doxygen like).
autosummary_generate
Konfiguration einrichten . Sie müssen eine Seite mit den automatischen Zusammenfassungen einrichten und die Seiten dann manuell bearbeiten. Sie haben Optionen, aber meine Erfahrung mit diesem Ansatz ist, dass viel zu viel Konfiguration erforderlich ist. Am Ende habe ich selbst nach dem Erstellen neuer Vorlagen Fehler und die Unmöglichkeit festgestellt, genau zu bestimmen, was als öffentliche API verfügbar gemacht wurde und was nicht. Meiner Meinung nach eignet sich dieses Tool für die Stub-Generierung, die manuell bearbeitet werden muss, und nicht mehr. Ist wie eine Abkürzung, um im Handbuch zu landen.Es gibt noch andere Optionen zu beachten:
quelle
__all__
Variable explicite einfügen muss.Sphinx ist hauptsächlich ein Tool zum Formatieren von Dokumenten, die nach meinem Verständnis unabhängig vom Quellcode geschrieben wurden.
Die wichtigsten Tools zum Generieren von API-Dokumenten aus Python-Dokumentzeichenfolgen sind pdoc und pydoctor . Hier sind die von pydoctor generierten API-Dokumente für Twisted und Bazaar .
Wenn Sie sich nur die Dokumentzeichenfolgen ansehen möchten, während Sie an Dingen arbeiten, gibt es natürlich das Befehlszeilentool " pydoc " und die
help()
im interaktiven Interpreter verfügbare Funktion.quelle
Ein weiteres sehr gutes Dokumentationswerkzeug ist die Sphinx . Es wird für die kommende Python 2.6- Dokumentation verwendet und von Django und vielen anderen Python-Projekten verwendet.
Von der Sphinx-Website:
quelle