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 manualeSe si tratta di
Manuale locale
o meno (vedi Manuali locali)Titolo
: il titolo per esteso del manualeDoc root
: l’elemento didocumentation
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 inizialeBase language
: la lingua principale del manualeVersion
: la versione del manualeAuthor
: l’autore del manualeSphinx 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 sitoExamples 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.
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.
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:
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