Configurazione

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

Suggerimento

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 Tag di Autorizzazione Documentation:

Suggerimento

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:

<xml_auth defaultTags="user,xml">
    <admin pwd="***" tags="superadmin,_DEV_,admin,user,_DOC_"/>
</xml_auth>

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:

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.

Suggerimento

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 package GENROBOT , se abilitare o meno l’invio delle notifiche agli utenti:

Il path di default se non specificato sarà documentation:handbooks, mentre la baseurl sarà costituita dal dominio dell’applicativo seguito dal suffisso docs.

Suggerimento

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 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

Suggerimento

Se intendi utilizzare 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/(?<prefix>[^/]+)(?<oth>(/.*)?)$ {
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 storage dei manuali su un bucket S3 e gestirne la distribuzione con Cloudfront.

Autore della sezione: Davide Paci