[Python] Doxygen -- creare documentazione

[Vittorio Zuccala']

Il giorno 16 giugno 2010 13.53, Daniele Varrazzo <piro a develer.com> ha
scritto:

> - 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.
>


Quello che apprezzo molto di questo sistema è la semplicità.
Poca configurazione, "linguaggio" estremamente semplice.
Estrae sia dalle docstring sia dai commenti: basta mettere il doppio
cancelletto per fagli capire che è un commento per il sistema.
Purtroppo non so ancora come eliminare dinamicamente classi in python ma mi
fido :-)
Mi piace molto anche il css utilizzato per fare il rendering delle pagine
HTML...


> - 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.
>


Dopo il messaggio di Vito De Tullio mi sono cimentato con questo sistema che
trovo molto potente.
Non mi entusiasma il rendering delle pagine HTML ma è una questione estetica
non certo funzionale.
Effettivamente mi sono accorto che la introspezione è molto completa anche
perchè proprio avvia il programma normalmente.
Per quanto riguarda le docstring quindi mi consigli il reST?
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...




> - 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.
>



Sempre dopo il messaggio di Vito ho provato anche questo sistema ma richiede
molto tempo (almeno per le mie conoscenze) per comprenderne il
funzionamento.
Sinceramente non me la sento di investirci tutto questo tempo...





> 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.
>


Caspita, questo si che è un bel consiglio!
Lo faccio subito perchè così provo tutti e tre i sistemi.
Quindi secondo te vale la pena investire del tempo per imparare sphinx...
Benissimo.
Ti ringrazio per il consiglio :-)
-------------- parte successiva --------------
Un allegato HTML è stato rimosso...
URL: http://lists.python.it/pipermail/python/attachments/20100616/12a26e0e/attachment.htm