Py a2 python-documentazione

813 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
813
On SlideShare
0
From Embeds
0
Number of Embeds
8
Actions
Shares
0
Downloads
8
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Py a2 python-documentazione

  1. 1. 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
  2. 2. 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
  3. 3. 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
  4. 4. 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
  5. 5. 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
  6. 6. 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
  7. 7. 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
  8. 8. 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
  9. 9. 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
  10. 10. 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
  11. 11. 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
  12. 12. 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
  13. 13. 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
  14. 14. 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

×