Pubblicazione in sphinx

La pubblicazione di una voce di Documentazione deve necessariamente passare preventivamente attraverso la creazione di un record della tabella Handbook e successivamente l’esportazione in manuale sphinx.

La tabella handbook

La tabella Handbook permette di identificare, partendo dalla tabella Documentazione, un albero di contenuti da pubblicare come manuale sphinx.

Le colonne di Handbook sono:

  • name: il nome identificativo del manuale
  • Doc Url: l’url dove verrà pubblicata la documentazione, in ambiente di produzione
  • Title: il titolo per esteso del manuale
  • Doc root: l’elemento di documentation che sarà la radice del manuale.
  • TOC roots: una volta specificato il docroot_id, potremmo voler specificare che gli elementi figli devono a loro volta essere radici di sottosezioni del manuale, dotate quindi ciascuna di un proprio indice (toc) nella pagina iniziale
  • Base language: la lingua principale del manuale
  • Version: la versione del manuale
  • Author: l’autore del manuale
  • Sphinx theme: il tema da utilizzare (se non presente nessun tema, verrà utilizzato lo Sphinx RTD Theme di default)
  • Sphinx path: il path nel sito dove verrà generato il progetto sphinx, compilato automaticamente
  • Examples site: se presenti degli esempi, corrispondente all’url del sito
  • Examples dir: se presenti degli esempi, corrisponde a «docu_examples»
  • Custom CSS: regole CSS personalizzate

Se presenti degli esempi, nei campi sottostanti che compariranno sarà possibile specificare un’altezza e una larghezza di default, la modalità di visualizzazione e un tema.

../_images/handbooks-generazione.png

Una volta specificati tutti o solo alcuni di questi parametri è possibile procedere con l’export cliccando sul bottone EXP. TO SPHINX. Comparirà un’ulteriore finestra con la richiesta di alcuni eventuali parametri addizionali, in particolare la possibilità di scaricare un file zip con la documentazione pubblicata in html:

../_images/download-zip.png

Se nelle Preferenze è stato attivato anche l’invio delle notifiche, la finestra dei parametri addizionali conterrà anche le informazioni necessarie per l’invio della notifica:

../_images/invio-notifiche.png

Di default l’invio sarà abilitato, ma è possibile disabilitarlo nel caso in cui non si voglia inviare questa specifica notifica (ad es. nel caso di modifiche minori). Il BOT sarà anche in questo caso quello di default, ma è possibile modificarlo a piacimento in caso ve ne siano altri configurati, così come il Contenuto della notifica.

I destinatari della notifica saranno i contatti iscritti al BOT così come configurato nel Package GENROBOT

Suggerimento

Si ricorda che per l’utilizzo della funzionalità di invio notifica è necessario aver preventivamente configurato il Il package GENROBOT e il collegato Service Telegram.

È inoltre possibile personalizzare il tema di Sphinx, inserire il codice di monitoraggio Google Analytics, produrre una sitemap. Per queste operazioni si rimanda alla successiva sezione Personalizzazioni .

Autore della sezione: Davide Paci