So dokumentieren Sie Python-Code mit Sauerstoff [geschlossen]

90

Ich mag Doxygen, um Dokumentation von C- oder PHP-Code zu erstellen. Ich habe ein bevorstehendes Python-Projekt und ich denke, ich erinnere mich, dass Python keine /* .. */Kommentare hat und auch eine eigene Selbstdokumentationsfunktion hat, die die pythonische Art zu dokumentieren scheint.

Wie kann ich meine Python-Dokumentation erstellen, da ich mit doxygen vertraut bin? Gibt es etwas Besonderes, das ich beachten muss?

Hanno Fietz
quelle

Antworten:

61

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_JAVAzu 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?

Blair Conrad
quelle
56
Kommentare als Dokumentation in Python sind schlecht. Kommentare sind für einen Modulbetreuer (warum und wie implementiert). Die gesamte Dokumentation sollte in Dokumentenzeichenfolgen enthalten sein (Verwendung).
JFS
4
Python zieht die Kommentare ein und verwendet sie als Dokumentzeichenfolgen, sodass beide Formate mit pydoc funktionieren.
docwhat
10
Schauen Sie sich doxypy an, mit dem Sie die speziellen Befehle in normalen Dokumentzeichenfolgen verwenden können.
Mauro
81

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.

if NewQuestion voteCLOSE
quelle
2
Es ist traurig, dass diese Antwort, die die richtige für die Frage ist, auch ganz unten steht :(
Dave Lasley
8
Vielleicht möchten Sie auch doxypypy ausprobieren, da es Pythonic-Dokumentzeichenfolgen in etwas konvertiert, das Doxygen verwenden kann.
Feneric
7
Doxypy scheint tot und weg zu sein ..
naught101
22

Am Ende haben Sie nur zwei Möglichkeiten:

Sie generieren Ihre Inhalte mit Doxygen oder Sie generieren Ihre Inhalte mit Sphinx *.

  1. 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 .

  2. Sphinx : Das Defacto-Tool zum Dokumentieren eines Python-Projekts. Hier haben Sie drei Möglichkeiten: manuell, halbautomatisch (Stub-Generierung) und vollautomatisch (Doxygen like).

    1. Für die manuelle API-Dokumentation haben Sie Sphinx Autodoc . Dies ist ideal, um ein Benutzerhandbuch mit eingebetteten API-generierten Elementen zu schreiben.
    2. Für halbautomatisch haben Sie Sphinx Autosummary . Sie können entweder Ihr Build-System so einrichten, dass es sphinx-autogen aufruft, oder Ihre Sphinx mit der autosummary_generateKonfiguration 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.
    3. Komplett automatisch. Dies wurde schon oft kritisiert und lange Zeit hatten wir keinen guten vollautomatischen Python-API-Generator in Sphinx integriert, bis AutoAPI kam, ein neues Kind im Block. Dies ist bei weitem das Beste für die automatische API-Generierung in Python (Hinweis: schamlose Eigenwerbung).

Es gibt noch andere Optionen zu beachten:

  • Atmen : Dies begann als eine sehr gute Idee und ist sinnvoll, wenn Sie mit mehreren verwandten Projekten in anderen Sprachen arbeiten, die Doxygen verwenden. Die Idee ist, die Doxygen XML-Ausgabe zu verwenden und sie Sphinx zuzuführen, um Ihre API zu generieren. So können Sie alle Vorteile von Doxygen beibehalten und das Dokumentationssystem in Sphinx vereinheitlichen. Theoretisch großartig. In der Praxis war das letzte Mal, als ich das Projekt überprüfte, noch nicht produktionsbereit.
  • pydoctor *: Sehr speziell. Erzeugt eine eigene Ausgabe. Es hat einige grundlegende Integration mit Sphinx und einige nette Funktionen.
Havok
quelle
Was ist der Befehl, um Autoapi zu verwenden. Ich habe die Datei conf.py so geändert, dass sie Autoapi-Module enthält. Derzeit führe ich "sphinx-apidoc -o apidocs --full" aus.
Sandeep
Sie benötigen keinen zusätzlichen Befehl. Erstellen Sie einfach Ihre Sphinx-Dokumentation mit Sphinx-Build. Ich habe es wie folgt in
Havok
@Havok Ich sehe nicht, wie AutoAPI "vollautomatisch" ist, wenn ich alle Elemente eines Moduls in die __all__Variable explicite einfügen muss.
Buhtz
20

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.

Allen
quelle
2
Es ist wahr, dass Sphinx Dokumente verwendet, die unabhängig vom Quellcode als Basis geschrieben wurden, aber mit der Autodoc-Erweiterung kann man problemlos Dokumentzeichenfolgen aus Python-Modulen einschließen. Aufgrund seiner Dynamik finde ich handgeschriebene Dokumentation für Python-Module nützlicher als generierte API-Dokumente.
Peter Hoffmann
3
"Handgeschriebene" Dokumente sind nicht verfügbar, wenn Sie versuchen, die Struktur und Beziehung zwischen Klassen in einem kaum dokumentierten Projekt zu untersuchen.
Ярослав Рахматуллин
13

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:

  • Ausgabeformate : HTML (einschließlich Windows HTML-Hilfe) und LaTeX für druckbare PDF-Versionen
  • Umfangreiche Querverweise : semantisches Markup und automatische Links für Funktionen, Klassen, Glossarbegriffe und ähnliche Informationen
  • Hierarchische Struktur : Einfache Definition eines Dokumentbaums mit automatischen Links zu Geschwistern, Eltern und Kindern
  • Automatische Indizes : allgemeiner Index sowie ein Modulindex
  • Code-Behandlung : Automatische Hervorhebung mit dem Textmarker Pylements
  • Erweiterungen : Automatisches Testen von Codefragmenten, Einfügen von Dokumentzeichenfolgen aus Python-Modulen und mehr
Peter Hoffmann
quelle
11
Habe es versucht. Obwohl Sphinx an sich ein sehr interessantes Werkzeug ist, war es nicht das, was ich von Sauerstoff erwartet hatte. Doxygen ist eher ein Tool für wirklich gute Endkundendokumente und viel besser für einen SW-Designer, der nur eine API-Übersicht in einem schönen druckbaren Format sehen möchte.
Zane
3
@ Zane Ich stimme zu. Als Doxygen-Liebhaber habe ich die vollautomatische Generierung von API-Referenzhandbüchern viel zu sehr vermisst. Überprüfen Sie meine Antwort, da jetzt eine andere Option verfügbar ist.
Havok