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:

../_images/handbooks-selezione-tema.png

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:

https://pypi.org/project/sphinx-sitemap/

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:

https://www.sphinx-doc.org/en/master/usage/theming.html

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:

../_images/analytics-theme-conf.png

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.