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.
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
HTML Logo
Sui documenti pubblicati con il design Docs Italia non c’è la possibilità di fare visualizzare un logo/immagine in alto a sinistra come, invece, avviene con la versione Read the Docs basic.
Quindi sul file conf.py
l’istruzione seguente
html_logo = "images/logo.png"
non deve essere data in questo caso. Se viene data la compilazione su Read the Docs fallisce.
Può essere editato cancelletto prima:
# html_logo = "images/logo.png"
così facendo l’istruzione non ha effetto in quanto tutto ciò che viene dopo cancelletto sul file conf.py
rappresenta un testo di commento e non un’istruzione da eseguire.
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/.
Qui il file
conf.py
= https://github.com/cirospat/joppy/blob/master/conf.py.Qui i dettagli dell’ultima compilazione del progetto Github in esame sulla piattaforma Read the Docs = https://readthedocs.org/projects/joppy/builds/7397980.
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 campisettings_basename
esettings_file_name
= linee-guida-open-data-comune-vattelapescasu 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.