.. _docs: ================================== 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/ 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``. .. note:: 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 :ref:`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 .. _`Rest primer`: http://sphinx-doc.org/rest.html#rst-primer .. _`Sphinx quickstart`: https://www.sphinx-doc.org/en/master/usage/quickstart.html .. _`ReST User Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html .. _`cloud_sptheme`: https://pythonhosted.org/cloud_sptheme/ .. _Sphinx: http://sphinx-org.doc/ .. _`Slides`: http://docs.thux.it/slides/corso/Sphinx.pdf