.. _package/docu/personalizzazioni:

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:  

.. image:: /_static/images/docu/handbooks-selezione-tema.png
    :width: 700px
    :align: center
    
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: 

.. image:: /_static/images/docu/analytics-theme-conf.png
    :width: 700px
    :align: center

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://sphinx-themes.org/

https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

.. sectionauthor:: Davide Paci