On Sun, 13 Jun 2010 11:39:19 +0200, "Vittorio Zuccala'" <vittorio.zucc...@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 _______________________________________________ Python mailing list Python@lists.python.it http://lists.python.it/mailman/listinfo/python
