Struttura e Interfaccia

Il pacchetto DOCU gestisce gli argomenti che andremo a inserire in un’ottica gerarchica, producendo un albero degli argomenti. Il primo step per produrre una buona Documentazione è quindi decidere gli argomenti che andremo a trattare, nonché l’ordine con cui lo faremo e i «rami» del nostro albero.

Il package DOCU è essenzialmente composto da una sola table primaria chiamata documentation, contenente i vari record a cui ci riferiremo con il termine voce di documentazione.

documentation è una tabella gerarchica e pertanto ne presenta le tipiche caratteristiche:

• un menu principale

• un albero di navigazione, con la ramificazione delle varie voci di documentazione

• un menu di navigazione (breadcrumb) per spostarsi ulteriormente tra i nodi dell’albero e creare voci «figlie»

• una visualizzazione a form della voce corrente

Menu principale

Il menu principale a sinistra ci permette di scegliere tra Documentazione e Handbooks.

La Documentazione raccoglie tutto il materiale che andiamo a produrre (le voci di documentazione), secondo la gerarchia che andiamo a definire.

Gli Handbooks raccoglie tutti gli argomenti (voci) della Documentazione che andiamo a pubblicare, tramite esportazione dei file in html secondo un processo che andremo a spiegare successivamente. La pubblicazione di una «Documentazione» non è quindi automatica e deve necessariamente passare dalla creazione di un Handbook. Secondo la stessa logica, non è detto che tutto ciò che è all’interno di una Documentazione (i rami dell’albero) venga trasferito a un Handbook, ma la pubblicazione può anche essere parziale.

Albero di navigazione

Essendo documentation una hierarchical table, l’intera struttura della table è presente direttamente nell’albero di navigazione sulla sinistra.

L’Albero di navigazione funziona con la classica logica del trascinamento di Genropy: per spostare i rami da un livello a un altro (o da una voce di documentazione a un’altra) è sufficiente trascinarlo dove si desidera.

Breadcrumb

La parte superiore della form è occupata da un ulteriore menu che permette di visualizzare dove ci troviamo all’interno della ramificazione gerarchica delle voci della Documentazione, ed eventualmente spostarci o creare nuove voci.

Per creare un argomento «figlio» di quello attuale useremo il + in alto al centro accanto alla ramificazione dell’argomento in cui ci troviamo, per creare invece un argomento «fratello» useremo il + in alto a destra.

La form per editare le voci

La form permette di editare il contenuto della voce in linguaggio RST e successivamente di visualizzarne l’anteprima. È possibile inserire vari parametri, tra cui:

• Nome del Documento, univoco e rappresentativo del nodo, che verrà utilizzato per la generazione dell’URL del file html (evitare quindi spazi e caratteri speciali)

• Data di pubblicazione, senza la quale il Documento non verrà pubblicato

• Titolo del Documento, versione «friendly» del Nome, che verrà invece visualizzato come title del file html e visualizzato nel nostro menu secondario

• altri parametri, come Revision, Topics, Doc. type, External reference, che possono essere utili ma che non utilizziamo per la Documentazione di Genropy e per cui di conseguenza rimandiamo ad altra sede.

Suggerimento

Ricordati di inserire la data di pubblicazione, altrimenti la tua voce di documentazione non verrà esportata in sphinx!

Immediatamente sotto ai dati principali notiamo un tab che distingue due voci:

• DOCUMENTAZIONE: Dedicato al contenuto vero e proprio della voce

• PARAMETRI: che serve per l’enumerazione di eventuali parametri, se l’argomento della voce fosse una classe o un metodo o una procedura con svariati parametri da elencare e spiegare. I parametri verranno presentati sotto forma tabellare per essere messi particolarmente in evidenza.

Contenuto multilingua

All’interno della form evidenziamo la presenza di un tab per le lingue, anche questo da preimpostare per essere utilizzato, che permette di gestire le varie traduzioni e anche di tradurre automaticamente il contenuto. La traduzione automatizzata viene effettuata tramite Yandex, sistema comodo perché ci fornisce una versione di base su cui lavorare senza dover ricostruire tutto il testo, ma allo stesso tempo non sempre efficacissimo, di conseguenza si invita a una seria revisione del testo in lingua straniera prima della pubblicazione.

Per il funzionamento del traduttore automatico è necessario registrarsi e impostare l’API key fornita dal servizio all’interno di siteconfig.xml:

<services>
        <rst2html theme='genropynet'/>
        <translation resource='yandex' api_key='la_tua_API_key' />
    </services>

Autore della sezione: Davide Paci