<div class="gmail_quote">Il giorno 16 giugno 2010 13.53, Daniele Varrazzo <span dir="ltr"><<a href="mailto:piro@develer.com">piro@develer.com</a>></span> ha scritto:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- doxygen e' nato per linguaggi statici, quindi effettua analisi dei<br>
sorgenti, estrae le docstring (forse anche qualcosa dai commenti, non ne<br>
sono sicuro) e usa quelli per la documentazione. Python però è un<br>
linguaggio dinamico: puoi creare ed eliminare dinamicamente classi,<br>
funzioni e oggetti dai sorgenti. Con doxygen questi elementi non possono<br>
essere documentati.<br></blockquote><div><br><br>Quello che apprezzo molto di questo sistema è la semplicità.<br>Poca configurazione, "linguaggio" estremamente semplice.<br>Estrae sia dalle docstring sia dai commenti: basta mettere il doppio cancelletto per fagli capire che è un commento per il sistema.<br>
Purtroppo non so ancora come eliminare dinamicamente classi in python ma mi fido :-)<br>Mi piace molto anche il css utilizzato per fare il rendering delle pagine HTML...<br> <br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- epydoc lo conosco bene, perché ne sono stato maintainer. Ora non è più<br>
molto mantenuto purtroppo: l'autore non mi sembra più tanto interessato al<br>
progetto. Comunque, effettua due fasi: una di scansione dei sorgenti<br>
(analoga a quella di Doxygen) e una di introspezione degli oggetti, quindi<br>
riesce a fare un lavoro più completo. Le docstring possono essere scritte<br>
in reST, che ormai è uno standard affermato in modo Python.<br></blockquote><div><br><br>Dopo il messaggio di Vito De Tullio mi sono cimentato con questo sistema che trovo molto potente.<br>Non mi entusiasma il rendering delle pagine HTML ma è una questione estetica non certo funzionale.<br>
Effettivamente mi sono accorto che la introspezione è molto completa anche perchè proprio avvia il programma normalmente.<br>Per quanto riguarda le docstring quindi mi consigli il reST?<br>Ho visto che usa l'epytext e il reST ma non conoscendo il secondo (tieni conto che uso python da molto poco) ho preferito l'epytext...<br>
<br><br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
- sphinx e' orientato a qualcosa di diverso rispetto a doxygen/epydoc,<br>
perché consente di scrivere tutta la documentazione di un progetto,<br>
includendo parti discorsive, procedure, esempi e non solo a documentare le<br>
API: dopo aver passato tanto tempo su Epydoc posso dire che i sistemi di<br>
documentazione di questo tipo raccontano solo una frazione della storia.<br>
Essendo un sistema molto estendibile, qualcuno ha realizzato un'estensione<br>
(autodoc) per fare introspezione degli oggetti: è sicuramente meno completa<br>
di Epydoc ma data l'integrazione col resto si sphinx e' sicuramente molto<br>
utile e controllabile.<br></blockquote><div><br><br><br>Sempre dopo il messaggio di Vito ho provato anche questo sistema ma richiede molto tempo (almeno per le mie conoscenze) per comprenderne il funzionamento.<br>Sinceramente non me la sento di investirci tutto questo tempo...<br>
<br><br><br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
Il confronto epydoc/sphinx è di prima mano, in quanto li ho usati entrambi<br>
per documentare psycopg: fallendo con epydoc (in quanto i doc dei sorgenti<br>
non sono mai stati integrati in una documentazione coerente) mentre invece<br>
il risultato con sphinx è stato perfetto (<a href="http://initd.org/psycopg/docs/" target="_blank">http://initd.org/psycopg/docs/</a>).<br>
In questa documentazione ho usato sia sphinx puro - per le parti<br>
discorsive, sia autodoc dove le docstring erano complete (es.<br>
<a href="http://initd.org/psycopg/docs/extensions.html" target="_blank">http://initd.org/psycopg/docs/extensions.html</a>). Se ti interessa sphinx puoi<br>
dare un'occhiata a come e' realizzata questa documentazione, sia scaricando<br>
i sorgenti del progetto che usando il link "show source" nelle pagine<br>
realizzate.<br></blockquote><div><br><br>Caspita, questo si che è un bel consiglio!<br>Lo faccio subito perchè così provo tutti e tre i sistemi.<br>Quindi secondo te vale la pena investire del tempo per imparare sphinx...<br>
Benissimo.<br>Ti ringrazio per il consiglio :-)<br><br></div></div>