Documentazione

Nei capitoli precedenti abbiamo letto in diverse occasioni che tutti gli oggetti hanno una variabile speciale chiamata __doc__ con la quale indichiamo lo scopo e l’utilizzo dell’oggetto. Questi sono i chiamati docstring o stringhe di documentazione.
Docstrings
A questi attributi si possono associare il testo in modo esplicito, assegnando al letterale la stringa corrispondente, come qualsiasi altra variabile. Tuttavia, per comodità, Python fornisce un meccanismo molto semplice ed è che se la prima riga della definizione dell’oggetto è una stringa, questa viene associata alla variable __doc__ automaticamente.
			def fai_qualcosa(arg):
			    """Questo è il docstring della funzione."""
			    print arg
			
			print fai_qualcosa.__doc__
			
			fai_qualcosa.__doc__ = """Questo è il nuovo docstring della funzione."""
			
			print fai_qualcosa.__doc__
Come si vede la cosa interessante di queste stringhe è che, a differenza dei normali commenti in Python e i commenti in altri linguaggi, le stringhe di documentazione non vengono rimosse dal bytecode, in modo che siano disponibili in fase di runtime, utilizzando, per esempio, la funzione help del linguaggio, o utilizzando l’istruzione print come nell’esempio precedente.
			>>> help(fai_qualcosa)
			Help on function fai_qualcosa in module __main__:
			fai_qualcosa(arg)
			Questo è il nuovo docstring della funzione.
Pydoc
La funzione help, di cui abbiamo visto prima, utilizza il modulo pydoc per generare la documentazione di un oggetto dalla sua docstring e le docstring dei suoi membri. Questo modulo, incluso di default con Python a partire dalla versione 2.1, si può importare nel nostro codice Python e utilizzarlo programmaticamente, oppure può essere utilizzata come uno strumento a riga di comando che sarebbe equivalente all’applicazione Javadoc del mondo Java.
pydoc può visualizzare l’informazione come testo sulla console, come come viene utilizzato da help, ma può anche generare dei file HTML come javadoc o facilitare le informazioni tramite un piccolo server web fornito con il modulo.
Pydoc è facile da usare. Con
			pydoc.py nome1 [nome2 ...]
se si mostra la documentazione del tema, modulo, classe, package, funzione o parola chiave specificata in modo simile alla funzione help. Se il nome è keywords, topics o modules si elencheranno le varie parole chiave, temi e moduli, rispettivamente.
Se si passa il flag -w, lo script conserverà la documentazione in uno o più file html invece di visualizzarlo sullo schermo.
			pydoc.py -w nome1 [nome2 ...]
Il flag -k viene utilizzato per cercare una determinata parola nella sinossi di tutti i moduli disponibili. La sinossi è la prima riga della stringa di documentazione.
			pydoc.py -k xml
Con -p si può avviare il server HTTP sulla porta indicata.
			pydoc.py -p porta
Una volta fatto questo si può accedere alla documentazione di tutti i moduli disponibili aprendo la pagina http://localhost:porta nel nostro browser.
Infine, utilizzando il flag -g possiamo essre in grado di lanciare una interfaccia grafica per cercare la documentazione che utilizza il server HTTP per visualizzare i risultati.
Epydoc e reStructuredText
Il problema pydoc e che è molto semplice, e non permette di aggiungere semantica o modificare gli stili della documentazione. Non possiamo, per esempio, indicaro che una linea particolare tra le linee di documentazione funzione descrive un parametro della funzione o visualizzare un certo termine in corsivo.
Ci sono progetti per generare la documentazione con caratteristiche più avanzate come Docutils, Epydoc o Sphinx, anche s’è necessario imparare delle sintassi speciali.
Docutils è un progetto sviluppato da David Goodger che comprende vari strumenti per generare la documentazione utilizzando il formato reStructuredText, un formato di testo piano creato dallo stesso autore, ed è il formato più utilizzato nella comunità Python. reStructuredText viene utilizzato, tra l’altro, per la creazione di PEP (Python Enhancement proposte).
Attualmente, tuttavia, Docutils è il più adatto per generare documenti da files di testo e non dai docstring estratti dal codice sorgente Python, in quanto il parser incaricato di fare questo lavoro è lungi dall’essere completato.
Epydoc è uno degli strumenti più utilizzato per la generazione della documentazione per Python. Oltre al testo normale e del suo proprio formato, chiamato epytext, supporta la sintassi reStructuredText e Javadoc, che i programmatori Java apprezzeranno.
Per il resto del capitolo useremo reStructuredText come linguaggio di markup e EpyDoc per generare i documenti finali.
Epydoc può essere scaricato dal loro sito web come installer exe per Windows, come pacchetto RPM per Fedora o simili, o come file zip tar.gz che include gli scripts per l’installazione: http://epydoc.sourceforge.net/ Lo troviamo anche nei repositori di varie installazioni Linux.
Una volta aver installato Epydoc seguendo il metodo adeguato al sistema operativo avremmo accesso alle funzionalità attraverso due distinte interfacce utente: lo script epydoc, che è una applicazione a riga di comando, e lo script epydocgui (in epydoc.pyw sotto Windows), che fornisce un’interfaccia grafica. In aggiunta si può anche accedere alle funzionalità di epydoc programmaticamente, come nel caso di pydoc.
Creiamo un piccolo modulo con un paio di classi per vedere prima il risultato dell’utilizzo di epydoc con docstring del semplice testo, senza alcuna marcatura speciale.
			"""Modulo para ejemplificar el uso de epydoc."""
			
			class Persona:
			    """Mia classe di esempio."""
			    def __init__(self, nombre):
			        """Inizializzatore della classe Persona."""
			        self.nombre = nombre
			        self.stampa_nome()
			
			    def stampa_nome(self):
			        """Stampa il nome della persona"""
			        print "Questa è la persona %s" % self.nombre
			
			class Impiegato(Persona):
			    """Sottoclasse di Persona."""
			    pass
			
			if __name__ == "__main__":
			    raul = Persona("Pippo")
Il formato di output predefinito di epydoc è HTML. Pertanto per generare la documentazione in formato HTML è sufficiente scrivere qualcosa di simile a questo:
			epydoc esempio.py
o anche
			epydoc --html esempio.py
Per generare un file PDF con LaTeX si usa il flag –pdf:
			epydoc --pdf esempio.py
Se LaTeX non installato o epydoc non riesce a trovare l’eseguibile, non sarà possibile generare il PDF.
Possiamo indicare anche il nome del progetto e l’URL utilizzando le opzioni --name e --url:
			epydoc --name Esempio --url http://www.miosito.net esempio.py
E anche aggiungere diagrammi che mostrano la classe base e le sottoclassi (--graph classtree), le chiamate tra le funzioni e metodi (--graph callgraph), le classi e sottoclassi utilizzando la notazione UML (--graph umlclasstree) o tutti loro (--graph all).
			epydoc --graph all esempio.py
Per generare il grafico di chiamate, tuttavia, è necessario generare un file con le informazioni necessarie utilizzando il modulo profile o il modulo hotshot e indicare il file risultante utilizzando il flag --pstat:
			epydoc --graph all --pstat profile.out esempio.py
Vediamo ora alcune funzionalità di base di markup in reStructuredText.
Per inserire il testo in corsivo si circonda il testo con un asterisco (*):
*italica* -> italica
Per inserire il testo in grassetto si circonda il testo con due asterischi (**):
**grassetto** -> grassetto
Per visualizzare il testo a spaziatura fissa (monospace), ad esempio per visualizzare il codice inline, viene usato le doppie virgolette ().
"monospace" -> monospace
Se abbiamo bisogno di usare qualsiasi di questi caratteri speciali si possono fare l’escape usando la barra rovesciata backslash (\).
\* è un carattere speciale -> * è un carattere speciale
Los títulos se crean añadiendo una línea de caracteres no alfanuméricos por debajo del texto, o por encima y por debajo del texto. Para crear un subtitulo basta utilizar una nueva combinación.
			Titolo
			======
			Sottotitolo
			———————————
Risultato

Titolo

Sottotitolo

Per creare una lista non ordinata ogni riga inizia con il carattere ‘*’, ‘-’ o ‘+’:
			* Python
			* C
			* Java
[/code
]
"Risultato"
<div><strong>· Python</strong></div> <div><strong>· C</strong></div> <div><strong>· Java</strong></div>
Per creare un elenco numerato la riga inizia con il numero seguito da un periodo, o con un <strong>#</strong> in modo che il numero venga inserito automaticamente.
1. Python 2. C 3. Java
Risultato
1. Python
2. C
3. Java
Per descrivere le proprietà degli elementi che stiamo documentando si utilizzano i campi o fields. Con reStructuredText i campi iniziano con : seguito dal nome del campo e opzionalemente dagli argomenti e si chiude di nuovo con : alla fine del corpo del campo.
Questi sono alcuni campi che Epydoc supporta:

Funzioni e metodi
:param p: Un parametro Descrive il parametro p.
:type p: str Specifica il tipo di ritorno previsto per il parametro p.
:return: True se sono uguali Valore di ritorno.
:rtype: str Tipo del valore di ritorno.
:keyword p: Un parametro Descrizione del parametro con il valore predefinito e il nome p.
:raise e: Se il parametro è zero Descrivere le circostanze per cui è generata l'eccezione e.
Variabili
:ivar v: Una variabile Descrizione dell'istanza v.
:cvar v: Una variabile Descrizione della variabile statica della classe v.
:var v: Una variabile Descrizione della variable v del modulo.
:type v: str Tipo della variabile v.
Note
:note: Una nota Una nota sull'oggetto.
:attention: Importante Una nota importante sull'oggetto.
:bug: Non funziona per il valore 0 Descrizione di un errore nell'oggetto.
:warning: Attenzione al valore 0 Un avvertimento circa un oggetto.
:see: Ver 'Python per tutti' Per indicare le relative informazioni.
Stato
:version: 1.0 La versione corrente dell'oggetto.
:change: Versione iniziale Lista di modifiche.
:todo: Internazionalizzazione Un progetto di adeguamento dell'oggetto.
:status: Versione stabile stato dell'oggetto.
Titolarità
:author: Mio Nome Autore o autori dell'oggetto.
:organization: Mia Impresa Organizzazione che ha creato o mantiene l'oggetto.
:license: GPL Licenza dell'oggetto.
:contact: account@mio_sito.net Informazioni di contatto dell'autore.

Per far sapere a Epydoc che vogliamo usare reStructuredText è necessario indicarlo attraverso la variabile __docformat__ nel codice o attraverso l'opzione --docformat nella linea di comando. Le opzioni possibili sono epytext, plaintext, reStructuredText o javadoc.
Vediamo un esempio con campi:

			"""Modulo per dimostrare l'uso di *epydoc*.
			    :author: Mio Nome
			    :version: 0.1"""
			__docformat__ = "restructuredtext"
			
			class Persona:
			    """Modella una persona."""
			    def __init__(self, nome, eta):
			        """Inizializzatore della classe `Persona`.
			           :param nome: Nome della persona.
			           :param eta: Età della persona"""
			        self.nome = nome
			        self.eta = eta
			        self.mostra_nome()
			
			def mostra_nome(self):
			    """Stampa il nome della persona"""
			    print "Questa è la persona %s" % self.nombre
			
			class Impiegato(Persona):
			    """Sottoclasse di `Persona` corrispondente alle persone 
			       che lavorano per l'organizzazione.
			       :todo: Scrivere implementazione."""
			    pass
			
			if __name__ == "__main__":
			    persona = Persona("Pippo", 26)
reStructuredText supporta anche un secondo tipo di campi in cui il corpo del campo è una lista. In questo modo possiamo, per esempio, descrivere tutti i parametri di una funzione o un metodo con un unico campo :Parameters: invece di un campo :param: per ciascun parametro.
			class Persona:
			    """Modella una persona."""
			    def __init__(self, nome, eta):
			        """Inizializzatore della classe `Persona`.
			
			           :Parameters:
			              - `nome`: Nome della persona.
			              - `eta`: Età della persona.
			        """
			
			    self.nome = nome
			    self.eta = eta
			    self.mostra_nome()
Altri campi che ammettono liste sono::Exceptions: per indicare le varie eccezioni (:except:), :Variables: per commentare su diverse variabili (:var:) oppure :Ivariables: per commentare le diverse istanze (:ivar:).


Similari
Overloading di metodi in Java
12% Java
Un metodo overload viene utilizzato per riutilizzare il nome di un metodo ma con argomenti diversi, opzionalmente con un differente tipo di ritorno. [expand title="Regole per overload" startwrap="" endwrap="" excerpt="⤽" s…
Modi di fare e di non fare in Python
11% Python
Questo documento può essere considerato un compagno del tutorial di Python. Viene illustrato come utilizzare Python, e quasi ancora più importante, come non usare Python. [expand title="Costrutti del linguaggio che non dov…
redirect 301 usando mod_alias
9% Server
mod_alias è fondamentalmente la versione più semplice di mod_rewrite. Non può fare le cose che fa mod_rewrite, ad esempio modificare la stringa di query. Per eseguire reindirizzamenti nel server web Apache è possibile di u…
Installare Python e Django su Windows
8% Django
Quando ci riferiamo allo sviluppo web con Python, la prima cosa che viene in mente è usare un qualche framework. Il più famoso e utilizzato da tutti è il Django, ma non è l'unico. Ci sono Pylons, Grok, TurboGears e Zope: t…
Metodi magici e costanti predefinite in PHP
8% Php
PHP fornisce un insieme di costanti predefinite e metodi magici per i nostri programmi. A differenza delle normali costanti i quali si impostano con define(), il valore delle costanti predefinite o speciali dipendono da do…