So dokumentieren Sie Python-Code mit Sauerstoff [geschlossen]

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?

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?

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.

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.

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.

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