.. _package/docu/pubblicazione: 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. .. image:: /_static/images/docu/handbook-form.png :width: 100% :align: center 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 :ref:`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 :ref:`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 :ref:`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. .. image:: /_static/images/docu/preferenze-export.png :width: 200px :align: center Inviare notifiche di aggiornamento *********************************** Se nelle :ref:`Preferenze` è stato attivato anche **l'invio delle notifiche**, la finestra dei parametri addizionali conterrà anche le informazioni necessarie per l'invio della notifica: .. image:: /_static/images/docu/invio-notifiche.png :width: 300px :align: center 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 :ref:`Package GENROBOT` .. hint:: Si ricorda che per l'utilizzo della funzionalità di invio notifica è necessario aver preventivamente configurato il :ref:`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 :ref:`Personalizzazioni` . Troubleshooting --------------- .. hint:: Qualcosa non ha funzionato? Controlla di aver :ref:`configurato` tutto correttamente. Ancora problemi? Chiedi aiuto sul `Gruppo AskGenropy `_ .. sectionauthor:: Davide Paci