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.

Creare un Manuale

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

Per creare un Manuale è necessario inserire:

  • Nome: il nome identificativo del manuale

  • Se si tratta di Manuale locale o meno (vedi Manuali locali)

  • Titolo: 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)

  • 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 non si tratta di manuale locale verrà anche proposto il campo di sola lettura Sphinx path, riportante il path dove verrà generato il progetto sphinx, compilato automaticamente.

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/handbook-form.png

Nella parte destra, invece, sarà possibile caricare un’immagine di anteprima sui motori di ricerca e sui social (ogp_image).

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 se saltare o meno la generazione dei file di reindirizzamento (se abilitata la gestione nelle Preferenze ).

Manuali locali

Se contraddistinto dal flag Manuale locale, l”handbook generato verrà compresso in un file zip e verrà proposto per il download.

Anziché il tab Anteprima con il frame della documentazione pubblicata verrà quindi proposto uno spazio dedicato al link per lo scaricamento del file.

Preferenze di esportazione

Al lancio dell’esportazione potrebbero essere richieste delle informazioni addizionali, in particolare:

  • se è stata abilitata nelle Preferenze la gestione dei redirect, può essere richiesto se saltare o meno la generazione dei redirect (Skip redirects)

  • se è in uso lo storage della documentazione con S3 e Cloudfront ed è stata indicata nelle preferenze una Cloudfront Distribution ID, è possibile Forzare l'invalidazione della cache e servire da subito i nuovi contenuti, senza attendere il refresh automatico.

../_images/preferenze-export.png

Inviare notifiche di aggiornamento

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.

Personalizzare il tema

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

Troubleshooting

Suggerimento

Qualcosa non ha funzionato? Controlla di aver configurato tutto correttamente. Ancora problemi? Chiedi aiuto sul Gruppo AskGenropy

Autore della sezione: Davide Paci