Come documentare il codice Python: Epydoc, doxygen, Sfinge, ...?

Question

Non sono sicuro se dovrei usare Epydoc o doxygen per documentare il mio codice Python. Attualmente preferirei Epydoc dato che è specializzato in Python e la sua sintassi non è molto diversa da quella di doxygen (che ho usato finora per documentare il mio codice C/C++).

Qualsiasi argomento contro Epydoc o per l'uso di doxygen?

• http://epydoc.sourceforge.net/
• http://www.doxygen.org/
• http://sphinx.pocoo.org/

Answer 1

Epydoc era stato il classico strumento per la generazione di documenti. Tuttavia, tutti ultimamente si stanno spostando verso la sfinge.

Si dovrebbe usare epydoc o si potrebbe provare a usare la sfinge. La documentazione di Python è essa stessa eseguita usando la sfinge. Sfinge può fornirti un maggiore controllo e una documentazione migliore.

• http://sphinx-doc.org/

Non c'è niente di sbagliato con doxygen ma fornisce una grande quantità di beneficio per C/C++ programmi. Poiché esistono strumenti doc specializzati per codice Python, possono fornire un controllo migliore sulla generazione di documenti.

Answer 2

Ho provato Sphinx, epydoc e doxygen per il mio progetto python.

Sphinx non ha funzionato per me in quanto dipende dalla possibilità di importare ogni modulo. Anche se il mio progetto funziona bene e Sphinx potrebbe trovare i suoi moduli, la Sfinge non è stata in grado di importare la maggior parte dei moduli. Sphinx può essere utile per la documentazione generale e per la creazione di un manuale utente, ma almeno per documentare il mio codice sorgente è inutile. Sembra che per il modulo Sphinx debba essere in grado di funzionare da solo. Ma nel mio progetto il primo modulo cerca di connettersi a un database. Se la connessione al database fallisce, si interrompe. Molti altri moduli prevedono un cursore di database. Se la connessione al database non è stata stabilita, non possono essere importati e quindi Sphinx fallisce.

Doxygen ha funzionato bene. Se combinato con doxypy è ancora meglio. Ha tuttavia alcuni inconvenienti. Se si desidera una lista numerata nel codice sorgente, non la si ottiene nella documentazione e viceversa. Inoltre, se si legge la documentazione, la fonte non è visibile.

Così ho provato Epydoc. Sebbene Epydoc non fosse stato aggiornato per più di 3 anni e quindi fosse morto, per me è risultato essere di gran lunga lo strumento migliore per documentare il codice Python. Epydoc, come Sphinx, prova ad importare ogni modulo, MA se l'importazione fallisce, mostra solo un messaggio di errore e quindi prova ad analizzare il modulo, come fa doxygen. La documentazione generata da Epydoc è buona e presenta alcuni vantaggi rispetto a doxygen: 1. La fonte documentata può essere resa visibile con un semplice clic. 2. Anche gli elenchi numerati in una docstring sono numerati nella documentazione.

L'installazione di Sphinx è piuttosto complicata se non è possibile utilizzare easy_install con connessione Internet. Questo perché Sphinx dipende da altri pacchetti. Doxygen può essere installato facilmente come la maggior parte dei programmi dotati di un programma di installazione con un solo clic. Ma dovrebbe essere installato anche DoxyPy e potrebbe essere gaphviz. Anche Expydoc può essere installato con un semplice clic, ma su Windows 7 questo deve essere fatto esplicitamente come admin, mentre il programma di installazione di Epydoc non controlla se è stato avviato con diritti sufficienti. Ottenere la prima documentazione utilizzabile del mio progetto è stato di gran lunga il più semplice e veloce con Epydoc. Infine, Epydoc può ancora essere raccomandato come lo strumento migliore per documentare i progetti Python. Sfinge può essere un buon strumento per produrre la documentazione dell'utente.