So dokumentieren Sie Python-Code mit doxygen [geschlossen]

StackOverflow https://stackoverflow.com/questions/58622

Frage

Ich mag doxygen, um Dokumentationen von C- oder PHP-Code zu erstellen.Ich habe ein bevorstehendes Python-Projekt und glaube mich zu erinnern, dass Python keins hat /* .. */ Kommentare und verfügt auch über eine eigene Selbstdokumentationsfunktion, die die pythonische Art der Dokumentation zu sein scheint.

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

War es hilfreich?

Lösung

Dies ist auf der doxygen Website dokumentiert, aber hier zusammenfassen:

Sie können die doxygen benutzen, um Ihre Python-Code zu dokumentieren. Sie können entweder die Python-Dokumentation String-Syntax verwenden: 

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

In diesem Fall werden die Kommentare werden von doxygen extrahiert werden, aber Sie werden nicht a href verwenden können, zu einem der <= „http://www.doxygen.nl/manual/commands.html#cmd_intro“ rel = "noreferrer"> spezielle doxygen Befehle .

oder Sie kann (ähnlich wie C-Stil Sprachen unter doxygen) das Kommentarzeichen (#) auf 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 doxygen-Befehle verwenden. Es gibt keinen bestimmten Python-Ausgabemodus, aber Sie können offenbar die Ergebnisse verbessern, indem OPTMIZE_OUTPUT_JAVA zu YES Einstellung.

Ehrlich gesagt, ich bin ein wenig überrascht über den Unterschied - es scheint, wie einmal doxygen die Kommentare in ## Blöcke erkennen kann, oder „““Blöcke, die meiste Arbeit getan werden würde und Sie würden in der Lage das zu verwenden, spezielle Befehle in jedem Fall. Vielleicht erwarten sie Menschen „““zu halten, um mehr Pythonic Dokumentation Praktiken verwenden und dass mit den speziellen doxygen Befehlen stören würde?

Andere Tipps

Die doxypy Eingangsfilter können Sie so ziemlich alle Doxygen der Formatierungs-Tags in eine verwenden, Standard Python docstring Format. Ich benutze es eine große gemischte C zu dokumentieren ++ und Python Spiel Anwendungs-Framework, und es funktioniert gut.

Sphinx ist in erster Linie ein Werkzeug für die docs Formatierung unabhängig vom Quellcode geschrieben, wie ich es verstehe.

Für API-Dokumentation von Python Docstrings zu erzeugen, die führenden Werkzeuge sind PDOC und pydoctor . Hier ist pydoctor die erzeugte API-Dokumentation für Verdrehte und Bazaar .

Natürlich, wenn Sie nur einen Blick auf die Docstrings haben wollen, während Sie auf Sachen arbeiten, gibt es die „ pydoc " Kommandozeilen-Tool und sowie die help() Funktion verfügbar im interaktiven Interpreter.

Am Ende haben Sie nur zwei Möglichkeiten:

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

  1. Sauerstoff:Für die meisten Python-Projekte ist es nicht das Werkzeug der Wahl.Wenn Sie sich jedoch mit anderen verwandten Projekten befassen müssen, die in C oder C++ geschrieben sind, kann dies sinnvoll sein.Hierfür können Sie die Integration zwischen Doxygen und Python mithilfe von verbessern doxypypy.

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

    1. Für die manuelle API-Dokumentation steht Ihnen Sphinx zur Verfügung Autodoc.Dies eignet sich hervorragend zum Schreiben eines Benutzerhandbuchs mit eingebetteten API-generierten Elementen.
    2. Für die Halbautomatik gibt es Sphinx automatische Zusammenfassung.Sie können entweder Ihr Build-System so einrichten, dass es Sphinx-Autogen aufruft, oder Sie können Sphinx mit dem einrichten autosummary_generate config.Sie müssen eine Seite mit den automatischen Zusammenfassungen einrichten und die Seiten dann manuell bearbeiten.Sie haben Optionen, aber meiner Erfahrung nach erfordert dieser Ansatz viel zu viel Konfiguration, und am Ende habe ich selbst nach der Erstellung neuer Vorlagen Fehler festgestellt und die Unmöglichkeit, genau zu bestimmen, was als öffentliche API bereitgestellt wurde und was nicht.Meiner Meinung nach ist dieses Tool gut für die Stub-Generierung geeignet, die eine manuelle Bearbeitung erfordert, und nichts weiter.Ist wie eine Abkürzung, um im Handbuch zu landen.
    3. Komplett automatisch.Dies wurde oft kritisiert und lange Zeit hatten wir keinen guten, vollautomatischen Python-API-Generator, der in Sphinx integriert war AutoAPI kam, das ist ein neues Kind im Block.Dies ist bei weitem das Beste für die automatische API-Generierung in Python (Hinweis:schamlose Eigenwerbung).

Es gibt weitere Optionen, die Sie beachten sollten:

  • Atmen:Dies war zunächst eine sehr gute Idee und macht Sinn, wenn Sie mit mehreren verwandten Projekten in anderen Sprachen arbeiten, die Doxygen verwenden.Die Idee besteht darin, die XML-Ausgabe von Doxygen zu verwenden und sie an Sphinx weiterzuleiten, um Ihre API zu generieren.So können Sie alle Vorzüge von Doxygen beibehalten und das Dokumentationssystem in Sphinx vereinheitlichen.Theoretisch großartig.In der Praxis war das Projekt, als ich das letzte Mal überprüfte, noch nicht produktionsreif.
  • Arzt*:Sehr speziell.Erzeugt eine eigene Ausgabe.Es verfügt über eine grundlegende Integration mit Sphinx und einige nette Funktionen.

Ein anderes sehr gute Dokumentation Tool Sphinx . Es wird für den kommenden Python verwendet wird 2.6 Dokumentation und wird von django und viele andere python-Projekte.

Von der Sphinx-Website:

  • Ausgabeformate : HTML (einschließlich Windows HTML-Hilfe) und LaTeX, für druckbare PDF-Versionen
  • Umfangreiche Querverweise : semantisches Markup und automatische Verknüpfungen für Funktionen, Klassen, Glossarbegriffe und ähnliche Informationen
  • Hierarchische Struktur : einfache Definition eines Dokumentenbaum, mit automatischen Links zu Geschwistern, Eltern und Kinder
  • Automatische Indizes : Gesamtindex sowie ein Modul-Index
  • Code-Handling : automatische Markierung mit dem Pygments Highlighter
  • Erweiterungen : automatische Testen von Code-Schnipsel, die Aufnahme von Docstrings von Python-Modulen und mehr
Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top