Personalizzazioni¶
Installare e modificare il tema¶
Per prima cosa è necessario installare il tema di default di Sphinx, sphinx_rtd_theme:
pip install sphinx-rtd-theme
Il tema verrà installato nelle Librerie di Python, all’interno della cartella site_packages
. Da lì sarà possibile o modificare il tema direttamente, o in alternativa eseguirne una copia da riportare poi manualmente nella propria installazione nella cartella di Genropy:
...genropy/projects/gnrcore/packages/docu/resources/sphix_env/themes/
In questo modo il tema verrà riportato nella tendina della form di Handbooks
e sarà selezionabile:
Generare automaticamente una Sitemap¶
Tramite un’apposita estensione è inoltre possibile produrre una sitemap in formato xml da segnalare a Google per una corretta indicizzazione del sito. Per prima cosa è necessario installare l’estensione nelle proprie Librerie Python:
pip install sphinx-sitemap
L’estensione è preconfigurata con baseurl /docs
e genererà automaticamente una sitemap all’indirizzo:
/docs/.../sitemap.xml
Per eventuali personalizzazioni si faccia riferimento all’apposita guida ufficiale:
Personalizzare il CSS¶
La form di Handbooks
contiene un’apposita sezione denominata Custom Styles
in cui è possibile andare ad inserire stili personalizzati.
Per tutte le altre personalizzazioni del tema si faccia riferimento a queste guide:
Autore e campi personalizzati¶
Autore, titolo documento, title e meta SEO, copyright e anno vengono direttamente letti dalla documentazione generata. In particolare, l’autore, se indicato nella singola voce della Documentazione, verrà visualizzato in coda alla pagina html generata. È necessario ripetere l’autore per ogni singola pagina, questo perché la Documentazione è pensata per essere redatta da più di un autore.
Inserire il tag di Google Analytics¶
È possibile inserire il tag di Google Analyitcs direttamente nel file theme.conf
del tema:
Per inserire in alternativa il tag di Google Tag Manager è necessario invece andare a personalizzare direttamente il tema.
Ruolo Documentatore¶
È previsto di default un ruolo per i «Documentatori», ovvero coloro che non avranno necessità di andare a fare modifiche all’applicativo, ma andranno solo a produrre Documentazione.
Il ruolo può essere aggiunto dalla sezione Amministrazione di sistema
>``Users setup``>``Tag di autorizzazione``, utilizzando come codice _DOC_, inserendo una Descrizione a piacimento e assegnando gli utenti incaricati.
Fonti e link utili¶
Altri link utili:
https://www.sphinx-doc.org/en/master/usage/configuration.html
https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
Autore della sezione: Davide Paci