[Python] Doxygen -- creare documentazione

[Daniele Varrazzo]

On Sun, 13 Jun 2010 11:39:19 +0200, "Vittorio Zuccala'"
<vittorio.zuccala a gmail.com> wrote:
> Grazie ad Alessandro: sono stato dormiente in lista per quasi un anno.
> Prima programmavo in C e perl adesso mi sto avvicinando a python
seriamente
> e mi piacerebbe dare dei contributi. Ci tengo molto alla condivisione.
> 
> Vito grazie per i link. Epydoc l'avevo visto in fase di ricerca ma non
ho
> approfondito.
> Penso che inizierò a guardare entrambi i links prima di "specializzarmi"
> con
> doxygen. Giusto per fare dei paragoni.

Ciao,

ho avuto a che fare con tutti questi sistemi, le mie impressioni sono
queste:

- doxygen e' nato per linguaggi statici, quindi effettua analisi dei
sorgenti, estrae le docstring (forse anche qualcosa dai commenti, non ne
sono sicuro) e usa quelli per la documentazione. Python però è un
linguaggio dinamico: puoi creare ed eliminare dinamicamente classi,
funzioni e oggetti dai sorgenti. Con doxygen questi elementi non possono
essere documentati.

- epydoc lo conosco bene, perché ne sono stato maintainer. Ora non è più
molto mantenuto purtroppo: l'autore non mi sembra più tanto interessato al
progetto. Comunque, effettua due fasi: una di scansione dei sorgenti
(analoga a quella di Doxygen) e una di introspezione degli oggetti, quindi
riesce a fare un lavoro più completo. Le docstring possono essere scritte
in reST, che ormai è uno standard affermato in modo Python.

- sphinx e' orientato a qualcosa di diverso rispetto a doxygen/epydoc,
perché consente di scrivere tutta la documentazione di un progetto,
includendo parti discorsive, procedure, esempi e non solo a documentare le
API: dopo aver passato tanto tempo su Epydoc posso dire che i sistemi di
documentazione di questo tipo raccontano solo una frazione della storia.
Essendo un sistema molto estendibile, qualcuno ha realizzato un'estensione
(autodoc) per fare introspezione degli oggetti: è sicuramente meno completa
di Epydoc ma data l'integrazione col resto si sphinx e' sicuramente molto
utile e controllabile.

Il confronto epydoc/sphinx è di prima mano, in quanto li ho usati entrambi
per documentare psycopg: fallendo con epydoc (in quanto i doc dei sorgenti
non sono mai stati integrati in una documentazione coerente) mentre invece
il risultato con sphinx è stato perfetto (http://initd.org/psycopg/docs/).
In questa documentazione ho usato sia sphinx puro - per le parti
discorsive, sia autodoc dove le docstring erano complete (es.
http://initd.org/psycopg/docs/extensions.html). Se ti interessa sphinx puoi
dare un'occhiata a come e' realizzata questa documentazione, sia scaricando
i sorgenti del progetto che usando il link "show source" nelle pagine
realizzate.

Ciao!

-- 
Daniele Varrazzo - Develer S.r.l. 
http://www.develer.com