[Python] Documentare Python

[Daniele Varrazzo]

On Wed, 14 Oct 2009 12:38:22 +0200, Antonello Mangone
<antonello.mangone a gmail.com> wrote:
> Ciao a tutti, posto una richiesta che spero non sia considerata troppo
> particolare.
> Non so se è fattibile, ma vorrei documentare Python in modo da produrre
dei
> documenti HTML in stile API di Java, PHP ecc ... o altrimenti in altri
> formati, ma comunque qualcosa di statico che può essere ovviamente
> aggiornato in maniera rapida, partendo dai commenti che vengono inseriti
> all'interno delle classi Python e delle funzioni o metodi.
> I commenti di cui parlo sono quelli che iniziano e finiscono con """ e
""",
> che vengono utilizzati da IDE evoluti per fornire documentazione di
classi
> e
> funzioni durante il loro uso.
> Un grosso grazie a chiunque riesca a fornirmi una dritta ... anche solo
> documentazione

Io ho partecipato a Epydoc (http://epydoc.sourceforge.net/), che forse è
stato il più completo progetto per generare le API dal codice Python.
Effettua sia introspezione che parsing del codice Python (in modo da
ottenere materiale sia da docstring che da commenti) e dà la possibilità di
linkare i commenti al codice, produrre grafi di dipendenza o uml e tanto
altro.

Sfortunatamente il progetto non è più tanto attivo: mi sembra che ora il
più attivo tra i progetti simili sia Sphinx (http://sphinx.pocoo.org/) che
è il sistema con cui viene creata la documentazione ufficiale del Python.
Non so che vantaggi abbia rispetto ad altri sistemi... ma se è riuscito a
mandare in pensione il sistema di documentazione precedente basato su
LaTeX, qualcosa di buono deve averlo! :)

Altra documentazione API notevole fatta con Sphinx è quella di Matplotlib
(es. vedi http://matplotlib.sourceforge.net/api/artist_api.html).

Insomma, anche se sono affezionato a Epydoc
(http://epydoc.sourceforge.net/api/epydoc.apidoc.ValueDoc-class.html non è
male, no?) ho paura che il futuro non passi di lì :\

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