Come scrivere la documentazione

Python

Scriviamo la documentazione per Python con Sphinx e la pubblichiamo sul sito https://docs.thux.it.

Sphinx è particolarmente idoneo a scrivere documentazione generica e usando le docstring di moduli, classi, metodi e funzioni.

Per le API abbiamo usato altri strumenti (redocs) ed al momento non abbiamo consigli definitivi.

Thux

Abbiamo personalizzato un tema per Thux partendo da cloud_sptheme . Il tema è uno dei pochi che nativamente prevede una toolbar dove mettiamo informazioni per passare da un progetto all’altro.

In generale ogni progetto viene pubblicato a questo indirizzo:

https://docs/thux.it/<package-name>

Il pacchetto thx-docs viene usato esclusivamente per scrivere documentazione (non ha codice), lo useremo per scrivere informazioni generiche non legate ad un singolo pacchetto. Nei pacchetti con codice la documentazione va scritta nel relativo pacchetto in modo che sia anche possibile documentare le api utilizzando l’instrospezione di Sphinx.

Sphinx è basato su ReST (Restructured Text) dal pacchetto docutils ma aggiunge molte direttive che ne fanno uno strumento più ricco ed adatto a progetti di grandi dimensioni (ad es: aggiunge introspezione del codice, riferimenti incrociati…)

Ecco alcuni link per avere un riferimento:

ReST User Reference

la user reference del team di docutils. Sono le direttive base supportate anche da PyCharm/VsCode

ReST primer

una introduzione dal sito di Sphinx

Sphinx quickstart

alcuni costrutti

Slides

le slide usate al corso

Ho creato alcune funzioni per generare la toolbar che ho messo nel pacchetto thx-sphinx che quindi diventa una dipendenza per la generazione della documentazione usando il nostro stile. Questa configurazione sta in docs/conf.py.

Nota

La toolbar è generata da ogni pacchetto, quindi non è la medesima e dipende da quale versione di thx-sphinx è stata usata per generare la doc del pacchetto.

generazione documentazione e virtualenv

Se vogliamo fare introspezione del codice è necessario che Sphinx venga eseguito nello stesso virtualenv dove ci sono tutte le dipendenze necessarie.

Le app generate con namespaced_app hanno già una cartella correttamente configurata allo scopo. Sarà quindi sufficiente:

cd docs
make html
make publish # servono i permessi sul server 'docs@docs.thux.it'

Per generare la documentazione. Se poi si ha a disposizione i tool del pacchetto jmb è possibile anche pubblicare:

dj docs
dj docs -u

make html compila e rigenera solo i file che sono stati modificati dopo l’ultima volta. Occasionalmente è necessario eliminare quanto già presente e poi rigenerare tutta la documentazione con i due comandi alternativi:

make clean
dj docs -c

Per esempio per aggiungere documentazione potremmo:

mkdir ~/src/thx
cd ~/src/thx
hg clone ssh://git@hg.thux.dev/thux/apps/thx/thx-docs
cd thx-docs
mkvirtualenv thx-docs
echo workon thx-docs > .env
poetry install
cd docs
make html     # genera la documentazione
xdg-open _build/html/index.html

per pubblicare la documentazione:

make publish

Javascript

TODO