.. _package/docu/configurazione_docu: Configurazione ============== .. toctree:: :maxdepth: 1 :hidden: :titlesonly: docu_s3 Prerequisiti ------------ Per un corretto utilizzo del package Docu è necessario aver installato Sphinx, il tema standard e le estensioni per la generazione della sitemap e dell'opengraph:: pip install -U sphinx pip install sphinx-rtd-theme pip install sphinx-sitemap pip install sphinxext-opengraph .. hint:: Potrebbe essere necessario eseguire l'installazione di *sphinx* con i privilegi di *superuser* (*sudo*) Impostazioni iniziali --------------------- Innanzitutto è necessario aver assegnato all'utente che si sta utilizzando (e a tutti gli utenti "documentatori") il :ref:`Tag di Autorizzazione` ``Documentation``: .. image:: /_static/images/docu/configurazione_docu/tag-autorizzazione-documentation.png :width: 200px :align: center .. hint:: Se si sta utilizzando l'utente ``admin`` di default di Genropy, è necessario modificare i tag di questo utente all'interno del file *instanceconfig.xml* globale:: Una volta entrati vedremo che si è automaticamente aggiunta la voce di menu *Documentazione*. Entriamo nella pagina ``Docu tables`` e inseriamo **almeno una lingua** per la nostra Documentazione: .. image:: /_static/images/docu/configurazione_docu/docu-set-lang.png :width: 800px :align: center Se abbiamo lanciato la *gnrdbsetup -u* troveremo pre-popolate le lingue italiano e inglese. Si noti che oltre al codice lingua (**obbligatoriamente di 2 caratteri**, secondo lo `standard ISO 639-2 `_), sarà possibile inserire anche le etichette da utilizzare per alcune voci. Se non impostate, verrà sempre utilizzata di default la dicitura in lingua inglese. .. hint:: Sei in Sandbox e non vedi la voce *Documentazione* nel menù? Probabilmente stai usando il menu di default dell'applicativo! Prova a cancellare o modificare manualmente il file ``menu.py`` che si trova nella tua cartella *config* della tua istanza. Inoltre dalle ``Preferenze`` generali dell'applicativo è possibile impostare un *path* (a piacere) sia per i manuali online che per quelli locali, una *baseurl* dove andremo a pubblicare i documenti, e, se abbiamo installato anche il :ref:`package GENROBOT` , se abilitare o meno :ref:`l'invio delle notifiche` agli utenti: .. image:: /_static/images/docu/configurazione_docu/preferenze.png :width: 300px :align: center Il *path* di default se non specificato sarà ``documentation:handbooks``, mentre la *baseurl* sarà costituita dal dominio dell'applicativo seguito dal suffisso `docs`. .. hint:: Qualora si intendesse personalizzare la *baseurl* si raccomanda di inserire una directory che termina con `/` come nella schermata di esempio Sia che questi due parametri siano stati modificati, sia che si stiano usando quelli di default, per pubblicare gli ``handbooks`` sarà prima necessario **istruire Nginx sul percorso**, in modo da reindirizzare l'url del manuale generato alla cartella corretta, come vedremo nel prossimo paragrafo. Si noti infine che è possibile specificare anche la ``Cloudfront Distribution ID``, che verrà utilizzata qualora si utilizzassero :ref:`S3 e Cloudfront` per lo storage della documentazione e si intendesse forzare manualmente la cancellazione della cache offrendo subito i nuovi contenuti senza attendere il refresh manuale della stessa. Configurazione di Nginx ----------------------- .. hint:: Se intendi utilizzare :ref:`S3 e Cloudfront` puoi saltare questo passaggio e andare direttamente alla documentazione dedicata Se desideriamo pubblicare la nostra documentazione sul server in produzione, nel file *conf* del nostro sito, che troveremo nella cartella ``etc/nginx/sites-enabled``, dovremo aggiungere la seguente istruzione:: location ~ ^/docs/(?[^/]+)(?(/.*)?)$ { alias /home/ubuntu/gitrepos/genropy_projects/nome_progetto/sites/nome_sito/path/$prefix/; try_files $oth $oth/ /index.html; #index index.html; autoindex on; } sostituendo ovviamente *^/docs* con la ``baseurl`` scelta, *nome_progetto* con il nome del progetto, *nome_sito* con il nome del sito, *path* con il path scelto nelle preferenze (equivalente a "documentation/handbooks" se non è stato variato il *documentation:handbooks* di default). In **alternativa alla configurazione di Nginx sinora descritta** è possibile effettuare lo :ref:`storage dei manuali su un bucket S3` e gestirne la distribuzione con Cloudfront. .. sectionauthor:: Davide Paci