Pubblicare con il design di Docs Italia

Se una Pubblica Amministrazione vuole sfruttare il servizio del componente aggiuntivo di Google doc, GGeditor, per pubblicare un documento su Read the Docs ma con il design di Docs Italia (elaborato dal Team Digitale per le pubblicazioni della PA), ecco alcune cose da tenere in considerazione al fine di non commettere errori che - alla fine - potrebbero non fare compilare la costruzione (build) del documento su Read the Docs e quindi pregiudicare la visualizzazione delle pagine HTML.

IMG1

Docs Italia parte dallo stile semplice di Read the Docs ma viene arricchito, dal Team Trasformazione Digitale, di “header” (parte superiore della pagina) e “footer” (parte inferiore della pagina) nella visualizzazione delle pagine html e di alcune novità in termini di personalizzazioni nella visualizzazione di alcuni contenuti testuali.

Ci sono differenze nel file conf.py del progetto con lo stile basic Read the Docs rispetto al file conf.py del progetto con il design Docs Italia del Team Trasformazione Digitale. Basta conoscerle e si eviteranno errori. Il file conf.py sul progetto Github è il cuore della configurazione che permette la corretta visualizzazione delle pagine html e la visualizzazione degli aggiornamenti fatti nelle pagine Google doc!

  • Qui un esempio di file conf.py del progetto con lo stile di base Read the Docs.

  • Qui un esempio di file conf.py del progetto con lo stile Docs Italia.

Evidente la differenza di istruzioni date nei due file.

Di seguito alcuni accorgimenti da tenere presenti nel lavoro da fare.


Uso corretto degli apici e doppi apici nel file ‘conf.py’

Nel file conf.py che si trova nel repository di Github, i doppi apici (“) vanno solo nel primo campo:

settings_project_name = "Nome progetto"

Nel resto dei settings vanno solo i singoli apici (‘).

Su setting_doc_version e su setting_doc_release va la dicitura ’version: latest’ (dentro apici singoli).

settings_copyright_copyleft = 'Comune di ...'
settings_editor_name = 'Comune di ...'
settings_doc_version = 'version: latest'
settings_doc_release = 'version: latest'
settings_basename = 'nome_progetto'
settings_file_name = 'nome_progetto'

Settaggi del file ‘conf.py’ nella sezione “Options for LaTeX output”

Nella sezione options for LaTex output dare le istruzioni seguendo esattamente questo codice di seguito riportato:

# -- Options for LaTeX output ------------------------------

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
#'preamble': '',
}

Praticamente l’istruzione 'papersize': 'a4paper', non deve avere davanti il simbolo del cancelletto (#).


Uso corretto dei titoli dei file Google doc dentro il toctree del file index

Nell’editing del nome dei file dei capitoli sul toctree, nel Google doc dell’index, deve essere inserito il suffisso .rst. Senza l’aggiunta del suffisso, sulle pagine html dello stile Docs Italia non comparirà la struttura dell’indice in home page.

Nel caso della pubblicazione su Read the Docs versione basic, (cioè senza il design Docs Italia elaborato dal Team Digitale per i documenti della PA) l’assenza di questo suffisso .rst per ogni file elencato nel toctree del file ‘index’ non costituisce un problema e l’indice viene visualizzato ugualmente sulle pagine html di Read the Docs.

Esempio di indice nel Google doc “index” nel caso di progetto Read the Docs: si nota l’assenza del suffisso .rst ad ogni titolo dei file elencati nel toctree

.. toctree::
    :maxdepth: 3
    :caption: Indice

    gdocs-rtd
    tutorial
    come-usarlo
    lavoro-github
    lavoro-rtd
    user-guide
    hypothesis-partecipazione
    pubblicare-su-docs-italia
    licenza

Esempio di indice nel Google doc “index” nel caso di progetto Docs Italia: si nota la presenza del suffisso .rst ad ogni titolo dei file elencati nel toctree

.. toctree::
    :maxdepth: 3
    :caption: Indice dei contenuti

    CARTA-SERVIZI-BIBLIOTECA-capitolo-1.rst
    CARTA-SERVIZI-BIBLIOTECA-capitolo-2.rst
    CARTA-SERVIZI-BIBLIOTECA-capitolo-3.rst
    CARTA-SERVIZI-BIBLIOTECA-appendice.rst

Un ‘progetto tipo’ da clonare per la pubblicazione con il design Docs Italia

A titolo di progetto tipo, da clonare su Github, per l’esigenza di creazione di un nuovo progetto di pubblicazione con il design Docs Italia, può essere usato questo repository su Github: https://github.com/cirospat/joppy dove sono state effettuate le necessarie verifiche nel file conf.py che permette un esatta compilazione del progetto sul design Docs Italia, ottenendo lo status verde di passing https://readthedocs.org/projects/joppy/.

E qui di seguito gli unici campi da personalizzare nel file conf.py:

settings_project_name = "cambiami_nome"
settings_copyright_copyleft = 'Comune di ...'
settings_editor_name = 'Comune di ...'
settings_doc_version = 'version: latest'
settings_doc_release = 'version: latest'
settings_basename = 'cambiami_nome'
settings_file_name = 'cambiami_nome'

Se sul sito Read the Docs avete dato, ad esempio, al progetto il titolo “linee guida open data comune vattelapesca”, allora nel campo settings_basename e nel campo settings_file_name date lo stesso nome così:

settings_basename = 'linee-guida-open-data-comune-vattelapesca'
settings_file_name = 'linee-guida-open-data-comune-vattelapesca'

Un ultimo consiglio per semplificare il lavoro

Cercate di dare lo stesso nome al progetto su Github, nel file conf.py di Github, e al progetto Read the Docs:

  • su Github il nome del progetto da creare = github/nome_account/linee guida open data comune vattelapesca

  • sul file conf.py di Github, rispettivamente nei due campi settings_basename e settings_file_name = linee-guida-open-data-comune-vattelapesca

  • su Read the Docs = linee guida open data comune vattelapesca

Questo vi consentirà di avere informazioni omogenee sui diversi ambienti dove andrete a lavorare, eliminando elementi che possono essere causa di errori o di confusione.


Aggiornamento 2020

AGID e il Dipartimento Trasformazione Digitale del Ministero Innovazione Tecnologica e Digitalizzazione hanno stabilito che:

  • https://docs.italia.it/ è la versione finale della piattaforma di pubblicazione della documentazione della Pubblica Amministrazione;

  • la piattaforma https://docs.italia.it/ può essere usata solamente per la pubblicazione di documenti prodotti dall’AGID e dal Ministero Innovazione Tecnologica e Digitalizzazione.

Ciò significa che qualsiasi altra Pubblica Amministrazione non può ospitare i propri documenti sulla piattaforma https://docs.italia.it/. Quindi qualunque PA può usare Read the Docs https://readthedocs.org per pubblicare documentazione e manuali online.