Sphinx e le sue potenzialità¶
L’intera documentazione generata della quale si sta usufruendo è frutto dell’unione tra Sphinx e JavaDoc, due strumenti dedicati alla generazione di testi a partire da del mero e puro codice.
Strumenti con cui è stata realizzata¶
Solitamente per documentare in maniera raffinata un progetto Java viene utilizzato lo strumento fornito dall’IDE di sviluppo stesso JavaDoc 1.
Esso offre degli incredibili vantaggi, come la facilità d’utilizzo e soprattutto un layout ben noto all’interno della community dei developers Java che permette di trovare informazioni in maniera decisamente veloce.
La pecca più grande di tale strumento però resta la datazione dei vari stili che compongono i file CSS e l’assenza di un’eleganza generale complessiva.
Per risolvere tale mancanza quindi si è pensato di ricorrere a Sphinx 2.
Poi mediante l’utilizzo di un’estensione nominata javasphinx 3 è stato possibile
convertire i vari commenti JavaDoc secondo lo standard perseguito da Sphinx stesso, e così
facendo abbiamo ottenuto sia una documentazione piacevole per la vista che
facile ed intutiva da poter seguire.
Autogenerazione della sintassi convertita da JavaDoc a Sphinx¶
Per fare questa operazione è necessario innanzitutto installare javasphinx
sulla propria macchina, attraverso il seguente comando:
$ pip install javasphinx
Una volta effettuato ciò sarà necessario inserire l’estensione javasphinx appena installata
nel file conf.py generato da Sphinx.
A questo bisognerà definire lo standard Java da seguire, all’interno del file
conf.py, nel seguente modo:
javadoc_url_map = { '<namespace_here>' : ('<base_url_here>', 'javadoc') }
Arrivati a questo punto basterà lanciare il comando:
$ javasphinx-apidoc -o docs/source/ --title='<name_here>' ../path/to/java_dirtoscan
La documentazione quindi sarà pronta per essere usata nei vari file con estensione .rst che, attraverso il comando make, diventaranno file .html.