Il documento fornisce informazioni sulla marcatura della documentazione in Python, inclusi meccanismi come le stringhe multilinea e l'attributo privato __doc__. Viene anche descritto l'uso della libreria esterna Sphinx per generare documentazione in formati diversi, tra cui HTML e JSON. Vengono forniti esempi pratici su come strutturare la documentazione e i requisiti per la creazione di file di configurazione.

2. ESEMPI:
(Cartella basic)
Introduzione doc_funzione1.py
doc_modulo1.py
A differenza del Perl, in Python non esiste un
formato apposito per la marcatura della
documentazione
Il runtime fornisce i seguenti meccanismi:
stringhe multilinea
attributi privati di oggetti per la memorizzazione
di documentazione ad essi relativa
Strumenti esterni:
generazione di documentazione in stile Javadoc
Linguaggi dinamici – A.A. 2009/2010
2

3. ESEMPI:
doc_funzione2.py
Stringhe multilinea doc_modulo2.py
doc_funzione_ufficiale.py
Una stringa contenuta fra due coppie di tri-
apici (“””) è considerata multi-linea
Non è necessario effettuare l'escape del
carattere RETURN al termine di ogni riga
“””
Prova di documentazione.
NB: non è
Questo testo si espande su più presente il
righe. carattere di
escape
”””
Linguaggi dinamici – A.A. 2009/2010
3

4. ESEMPI:
usage.py
Stampa dello usage di un programma
Il messaggio di uso di un programma (usage),
stampato in seguito ad un erroneo ingresso
oppure in seguito all'opzione di help (-h), è
solitamente implementato tramite una stringa
multi-linea
print “””Usage: programma arg1 [arg2]
arg1: descrizione argomento 1
arg2: descrizione argomento 2
“””
Linguaggi dinamici – A.A. 2009/2010
4

5. L'attributo privato __doc__
In Python, qualunque entità (variabile,
funzione, istanza di oggetto) può essere vista
come un oggetto
A ciascun oggetto è associato un attributo
privato, __doc__
Tale attributo contiene una descrizione
documentale dell'oggetto
La descrizione può essere fornita tramite una
stringa oppure tramite una stringa multilinea
__doc__ è un attributo in sola lettura; non può
essere sovrascritto, solo impostato inizialmente
Linguaggi dinamici – A.A. 2009/2010
5

6. L'attributo privato __doc__
L'impostazione dell'attributo privato __doc__
avviene tramite l'inserimento di stringhe
normali o multilinea (dette docstring) in
posizioni strategiche del codice
Le posizioni strategiche sono le seguenti
Modulo: una stringa subito al di sotto della
shebang #!
Funzione: una stringa subito al di sotto della
definizione di funzione
Linguaggi dinamici – A.A. 2009/2010
6

7. ESEMPI:
Animale.py
Produzione di documentazione
Per convenzione, la documentazione di una
funzione è conseguita tramite l'uso di una
stringa multilinea
La prima linea è una descrizione breve dello
scopo della funzione (cosa fa, non come lo fa)
Obbligatoria
Segue una riga vuota
Segue un paragrafo che spiega in dettaglio:
significato dei parametri
risultato atteso
eventuali effetti collaterali
Linguaggi dinamici – A.A. 2009/2010
7

8. ESEMPI:
Cartella sphinx
Strumenti esterni: sphinx
Una libreria esterna di ausilio alla produzione
di documentazione è sphinx
http://sphinx.pocoo.org/
sudo easy-install sphinx
Sphinx introduce il meccanismo dei tag (tipico
di perldoc e javadoc) nel codice Python
Formato di markup: reST (reStructuredText)
http://docutils.sourceforge.net/rst.html
Linguaggi dinamici – A.A. 2009/2010
8

9. Generazione di documentazione
Si utilizza il comando sphinx-quickstart
http://matplotlib.sourceforge.net/sampledoc/
getting_started.html
Viene generato automaticamente un template
per la documentazione e i makefile per
windows e unix/linux/osx
Si utilizza il comando
make target
per produrre la documentazione in uno dei
formati supportati.
Linguaggi dinamici – A.A. 2009/2010
9

10. Generazione di documentazione
Possibili valori di target:
html to make standalone HTML files
dirhtml to make HTML files named index.html in directories
pickle to make pickle files
json to make JSON files
htmlhelp to make HTML files and a HTML help project
qthelp to make HTML files and a qthelp project
latex to make LaTeX files
changes to make an overview of all changed/added/
deprecated items
linkcheck to check all external links for integrity
doctest to run all doctests embedded in the documentation
(if enabled)
Linguaggi dinamici – A.A. 2009/2010
10

11. Generazione di documentazione
Il file index.rst è il file master, è possibile
modificarlo per inserire i vari contenuti, ad es:
.. toctree::
:maxdepth: 2
contents
(Inserisce nel documento il file contents.rst)
Linguaggi dinamici – A.A. 2009/2010
11

12. Generazione di documentazione
Dentro il file contents.rst:
MioModulo
=========
.. automodule:: MioModulo
:members:
(crea una sezione “MioModulo” e genera
automaticamente la documentazione del
modulo “MioModulo”)
Le opzioni immutabili possono essere scritte
in un file di configurazione conf.py
Linguaggi dinamici – A.A. 2009/2010
12

13. Tag di descrizione
Ciascun tag va inserito all'interno di una
normale docstring
Tag di descrizione disponibili
Paragrafi di testo
Elenchi numerati e non
Blocchi letterali (verbatim)
Inline markup (italic, bold, codice sorgente, …)
Parametri (tipo, descrizione)
Valori di ritorno
…
Linguaggi dinamici – A.A. 2009/2010
13

14. Tag di descrizione
Paragrafo di testo
Una o più righe di testo, allineate a sinistra
Elenco numerato
Elenco di righe, ciascuna delle quali inizia con
un bullet numerico (1., 2., 1.2.8)
Elenco non numerato
Elenco di righe, ciascuna delle quali inizia con
un bullet non numerico (-)
Linguaggi dinamici – A.A. 2009/2010
14

15. Tag di descrizione
Sezione di un libro
Una riga contenente il titolo della sezione,
seguita da una riga di caratteri speciali a
sottolineare il titolo stesso (lunga almeno
quanto il titolo)
Sezione principale: carattere =
Sottosezione: carattere -
Sotto-sottosezione: carattere ^
Paragrafi: carattere “
Linguaggi dinamici – A.A. 2009/2010
15