Mi piace che Doxygen crei documentazione di codice C o PHP. Ho un imminente progetto Python e penso di ricordare che Python non ha /* .. */commenti e ha anche una propria funzione di auto-documentazione che sembra essere il modo pitonico 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?
Risposte:
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 di documentazione di 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 comandi speciali di doxygen .
Oppure puoi (simile ai linguaggi in stile C sotto doxygen) raddoppiare il marcatore di 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 usare i comandi speciali doxygen. Non esiste una particolare modalità di output Python, ma a quanto pare puoi migliorare i risultati impostando OPTMIZE_OUTPUT_JAVAsu YES.
Onestamente, sono un po 'sorpreso della differenza: sembra che una volta che doxygen possa rilevare i commenti nei blocchi ## o nei blocchi "" ", la maggior parte del lavoro sarebbe stata eseguita e saresti stato in grado di usare i comandi speciali in In entrambi i casi, forse si aspettano che le persone che usano "" "aderiscano a più pratiche di documentazione Pythonic e questo interferirebbe con i comandi speciali di doxygen?
Il filtro di input doxypy ti consente di utilizzare praticamente tutti i tag di formattazione di Doxygen in un formato docstring Python standard. Lo uso per documentare un grande framework misto di applicazioni di gioco C ++ e Python, e funziona bene.
Alla fine, hai solo due opzioni:
Genera i tuoi contenuti usando Doxygen o generi i tuoi contenuti usando Sphinx *.
Doxygen : non è lo strumento preferito dalla maggior parte dei progetti Python. Ma se hai a che fare con altri progetti correlati scritti in C o C ++ potrebbe avere senso. Per questo puoi migliorare l'integrazione tra Doxygen e Python usando doxypypy .
Sphinx : lo strumento di fatto per documentare un progetto Python. Hai tre opzioni qui: manuale, semiautomatica (generazione di stub) e completamente automatica (tipo Doxygen).
autosummary_generateconfig. Sarà necessario impostare una pagina con i riassunti automatici, 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 trovato bug e l'impossibilità di determinare esattamente cosa era esposto come API pubblica e cosa no. La mia opinione è che questo strumento è buono per la generazione di stub che richiederà la modifica manuale e nient'altro. È come una scorciatoia per finire in manuale.Ci sono altre opzioni da notare:
__all__variabile explicite.
Sphinx è principalmente uno strumento per la formattazione di documenti scritti indipendentemente dal codice sorgente, a quanto ho capito.
Per la generazione di documenti API da docstring Python, gli strumenti principali sono pdoc e pydoctor . Ecco i documenti API generati da pydoctor per Twisted e Bazaar .
Ovviamente, se vuoi solo dare un'occhiata alle docstring mentre lavori, c'è lo strumento a riga di comando " pydoc " e anche la help()funzione disponibile nell'interprete interattivo.
Un altro ottimo strumento di documentazione è Sphinx . Verrà utilizzato per la prossima documentazione di python 2.6 ed è utilizzato da django e da molti altri progetti python.
Dal sito web della Sfinge: