La documentazione è integrata all'interno dei sorgenti nelle docstrings the diversi moduli. Come lo standard impone, ogni elemento pubblico del modulo è documentato e ogni modulo espone la lista di simboli esportati tramite la variabile globale '__all__'.
La scelta della sintassi da usare nella documentazione, per velocizzare i tempi di sviluppo e rendere la documentazione più leggera, è una sintassi arbitraria, caratterizzata però da una certa uniformità.
Le sezioni della documentazione sono caratterizzate dal simbolo @ seguite dal nome della sezione. Segue una lista delle principali sezioni:
La documentazione html è generata tramite il tool pydoc,
normalmente presente di default nelle comuni installazioni python.
E' possibile accedere alla documentazione dal seguente link:
pcisim.html
La documentazione è consultabile anche da terminale utilizzando lo script pydoc:
La documentazione in formato html può essere rigenerata in un sistema GNU/Linux posizionandosi nel percorso ./doc/pydoc/ relativo a questa distribuzione e lanciando lo script:
Opzionalmente è possibile specificare un percorso pythonico del solo modulo per cui si desidera rigenerare la documentazione.
N.B. per percorso pythonico s'intende un percorso separato da caratteri punto tipico degli imports di python.
E' possibile installare il pacchetto pcisim in modo
system-wide, per poter disporre della libreria associata
e della documentazione da terminale da qualunque percorso di
sistema.
Per conoscere il percorso in cui vengono installati i pacchetti
di sistema in python provare ad eseguire il seguente comando:
python -c "import os; print os.path.join(os.path.dirname(os.__file__), 'dist-packages')"
nel mio caso /usr/lib/python2.7/dist-packages. Una copia di pcisim (presente nella cartella src) all'interno della cartella designata dovrebbe realizzare correttamente l'installazione system-wide.
Il simulatore 'PCI Bus Simulator' fa parte di un pacchetto di software chiamato pcisim. Questo include tutti i moduli python interni necessari al funzionamento del simulatore. In particolare il pacchetto è composto dai seguenti packages:
In particolare il package pcisim.lib contiene al suo interno i seguenti sotto pacchetti:
Per avere informazioni sui pacchetti specifici e su come aggiungere nuove funzionalità ad essi visitare la pagina specifica della documentazione.
Il simulatore è sviluppato secondo il paradigma di programmazione orientata agli oggetti. I widgets comunicano tra di loro utilizzando un sistema ad eventi costruito con gli strumenti forniti da WxPython. Fare riferimento alla documentazione del modulo pcisim.core.events per avere maggiori informazioni.
Per quanto riguarda la strategia di programmazione, si è cercato di adottare una tecnica MCV (Model Controller View), ovvero dividere le strutture dati dalla loro presentazione.
Buona parte delle strutture dati implementate in pcisim.data sono costruite a partire dalla classe DataWord pcisim.lib.dataword che fornisce un interfaccia abbastanza intuitiva per implementare strutture dati differenti. Questo può essere considerato il Model della MCV.
La parte di View è invece svolta dalla classe DataView fornita dal modulo pcisim.widgets.dataview. Questa classe è in grado di visualizzare il contenuto dei singoli campi dati e fornisce un buon grado di personalizzazione delle modalità di presentazione.
Se abbinata alla funzione di slots fornita dal modulo pcisim.lib.datafield, dalla stessa DataView è possibile settare i valori dei campi tra quelli disponibili, implementando di fatto la funzione di Controller. Questo è ad esempio usato per permettere la modifica della configurazione interna dei dispositivi PCI.
Il pacchetto pcisim fornisce un'interfaccia per il test dei singoli
moduli presenti in esso. Questo permette di velocizzare le fasi
di debug dei moduli e suggerisce una maggiore separazione in base
a funzionalità fornite.
Il modulo dedicato al module testing è
pcisim.core.modbuild
In breve, i moduli sviluppati dentro pcisimo possono esporre una delle seguenti interfacce:
Per testare un modulo che supporta l'unit testing è necessario posizionarsi nella cartella ./src/pcisim relativa alla distribuzione e lanciare il comando:
dove [modulepath] è il percorso relativo al modulo da testare.
Solo alcuni moduli del pacchetto pcisim implementano effettivamente delle funzioni di testing.
Il simulatore può essere sicuramente migliorato sia in termini di
funzionalità che in termini di usabilità.
Ecco alcuni miglioramenti suggeriti:
Si consiglia la visione di questi appunti relativi a WxPython scritti in italiano che ben documentano gli oggetti principali del modulo:
Gli argomenti trattati sono i seguenti: