Come documentare il codice Python con doxygen [chiuso]

Question

Mi piace doxygen per creare documentazione di codice C o PHP.Ho un progetto Python imminente e penso di ricordare che Python non ha /* .. */ commenti e ha anche una propria struttura di autodocumentazione che sembra essere il modo Python di documentare.

Dato che ho familiarità con doxygen, come posso usarlo per produrre la mia documentazione Python?C'è qualcosa in particolare di cui devo essere a conoscenza?

Answer 1

Questo è documentato sul sito web di doxygen, ma per riassumere qui:

Puoi usare doxygen per documentare il tuo codice Python.Puoi utilizzare la sintassi della stringa della documentazione Python:

"""@package docstring
Documentation for this module.

More details.
"""

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

    More details.
    """
    pass

In tal caso i commenti verranno estratti da doxygen, ma non sarai in grado di utilizzare nessuno dei file comandi speciali di doxygen.

O puoi (simile ai linguaggi in stile C sotto doxygen) raddoppiare l'indicatore del commento (#) sulla prima riga prima del membro:

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

In tal caso, puoi utilizzare gli speciali comandi doxygen.Non esiste una modalità di output particolare di Python, ma a quanto pare puoi migliorare i risultati impostando OPTMIZE_OUTPUT_JAVA A YES.

Onestamente, sono un po' sorpreso dalla differenza: sembra che una volta che doxygen possa rilevare i commenti nei blocchi ## o nei blocchi """, la maggior parte del lavoro verrebbe svolto e sarai in grado di utilizzare i comandi speciali in in entrambi i casi.Forse si aspettano che le persone che usano """ aderiscano a più pratiche di documentazione Python e ciò interferirebbe con gli speciali comandi doxygen?

Answer 2

IL doxypy il filtro di input ti consente di utilizzare praticamente tutti i tag di formattazione di Doxygen in un formato docstring Python standard.Lo uso per documentare un ampio framework di applicazioni di gioco misto C++ e Python e funziona bene.

Answer 3

Sphinx è principalmente uno strumento per formattare documenti scritti indipendentemente dal codice sorgente, a quanto ho capito.

Per generare documenti API da docstring Python, gli strumenti principali sono pdoc E pydoctor.Ecco i documenti API generati da pydoctor per Contorto E Bazar.

Naturalmente, se vuoi semplicemente dare un'occhiata alle docstring mentre lavori, c'è il "pydoc" strumento da riga di comando e anche il file help() funzione disponibile nell'interprete interattivo.

Answer 4

Alla fine hai solo due opzioni:

Generi i tuoi contenuti utilizzando Doxygen oppure generi i tuoi contenuti utilizzando Sphinx*.

1. Dossigeno:Non è lo strumento preferito per la maggior parte dei progetti Python.Ma se devi occuparti di altri progetti correlati scritti in C o C++ potrebbe avere senso.Per questo puoi migliorare l'integrazione tra Doxygen e Python utilizzando doxypypy.

2. Sfinge:Lo strumento di fatto per documentare un progetto Python.Hai tre opzioni qui:manuale, semiautomatico (generazione di stub) e completamente automatico (come Doxygen).

   1. Per la documentazione API manuale hai Sphinx autodoc.È fantastico scrivere una guida per l'utente con elementi generati dall'API incorporati.
   2. Per il semiautomatico c'è Sphinx riepilogo automatico.Puoi configurare il tuo sistema di build per chiamare sphinx-autogen o configurare Sphinx con il file autosummary_generate config.Sarà necessario impostare una pagina con i riepiloghi automatici e quindi modificare manualmente le pagine.Hai delle opzioni, ma la mia esperienza con questo approccio è che richiede troppa configurazione e alla fine, anche dopo aver creato nuovi modelli, ho riscontrato bug e l'impossibilità di determinare esattamente cosa era esposto come API pubblica e cosa no.La mia opinione è che questo strumento sia utile per la generazione di stub che richiederà la modifica manuale e niente di più.È come una scorciatoia per finire nel manuale.
   3. Completamente automatico.Questo è stato criticato molte volte e per molto tempo non abbiamo avuto un buon generatore di API Python completamente automatico integrato con Sphinx fino a quando API automatica è arrivato, che è un nuovo ragazzo nel blocco.Questo è di gran lunga il migliore per la generazione automatica di API in Python (nota:autopromozione spudorata).

Ci sono altre opzioni da notare:

• Respirare:questa è iniziata come un'ottima idea e ha senso quando lavori con diversi progetti correlati in altre lingue che utilizzano Doxygen.L'idea è di utilizzare l'output XML di Doxygen e inviarlo a Sphinx per generare la tua API.Quindi, puoi mantenere tutta la bontà di Doxygen e unificare il sistema di documentazione in Sphinx.Fantastico in teoria.Ora, in pratica, l'ultima volta che ho controllato il progetto non era pronto per la produzione.
• pydoctor*:Molto particolare.Genera il proprio output.Ha alcune integrazioni di base con Sphinx e alcune funzionalità interessanti.

Answer 5

Un altro ottimo strumento di documentazione è sfinge.Verrà utilizzato per il prossimo Python 2.6 documentazione ed è utilizzato da django e molti altri progetti Python.

Dal sito web della Sfinge:

• Formati di output:HTML (inclusa la Guida HTML di Windows) e LaTeX, per versioni PDF stampabili
• Riferimenti incrociati estesi:markup semantico e collegamenti automatici per funzioni, classi, termini di glossario e informazioni simili
• Struttura gerarchica:facile definizione di un albero dei documenti, con collegamenti automatici a fratelli, genitori e figli
• Indici automatici:indice generale e indice dei moduli
• Gestione del codice:evidenziazione automatica utilizzando l'evidenziatore Pygments
• Estensioni:test automatico di frammenti di codice, inclusione di docstring da moduli Python e altro ancora