Tutorial
Le spiegazioni contenute in questo tutorial rappresentano una via per migliorare la qualità dei documenti pubblicati sul web e sono la traduzione in italiano del tutorial GGeditor. Il tutorial spiega come usare lo strumento di Google doc, ed un componente aggiuntivo, per pubblicare documenti con lo stile di Read the Docs, utilizzando anche GitHub.
Questo documento nasce subito dopo la produzione del tutorial “Come abbiamo creato un «Read the Docs» per pubblicare documenti pubblici su Docs Italia”.
Per questo tutorial i seguenti ringraziamenti particolari
Ringraziare queste persone è importante, perché con i loro approfondimenti hanno permesso di ampliare le possibilità d’uso di Read the Docs come piattaforma di pubblicazione documentale:
Hsin Yuan Yeh, Andrea Borruso, Giovan Battista Vitrano, Salvatore Fiandaca, Pablo Persico, Marina Bassi, Andrea Ivan Baldassarre, Daniele Rizzo, Maurizio Costa, Michela Stentella.
L’uso di Read the Docs come piattaforma di pubblicazione di documenti online ha i seguenti vantaggi rispetto al formato :guilabel:`PDF`:
Responsive
Funzioni avanzate di ricerca testo
Fornisce testo in HTML, EPUB e PDF
Codice sorgente del testo online
E’ elegante e bello da vedere
Per i nostalgici e dipendenti da documenti in formato :guilabel:`PDF` (non accessibili comodamente da dispositivi mobili), la documentazione esposta su Read the Docs permette di scaricare il contenuto dell’intero documento pubblicato online sia in formato :guilabel:`PDF` che :guilabel:`EPUB` oltre che :guilabel:`HTML`.
Registro di tutti gli aggiornamenti | modifiche principali apportate al progetto
Aggiornamento N. 1 - gennaio_2020
Su Google doc cliccando su “installa componente aggiuntivo” non trovate più “GGeditor” neanche sul Marketplace di Google (capita dall’agosto 2019 per una ridefinizione dei termini d’uso di Google). Passate alla procedura del successivo aggiornamento.
Aggiornamento N.2 - 14_febbraio_2020
In alternativa all’installazione del componente aggiuntivo su Google doc (dall’elenco dei componenti aggiuntivi forniti da Google), le funzioni svolte da GGeditor possono anche essere assicurate creando un Google doc che contiene uno script con il codice sorgente del componente GGeditor. Una volta creato lo script (con la procedura di seguito illustrata) avviando il comando “Commit to Github” (percorso: componenti aggiuntivi / GGeditor / Commit to Github), è possibile creare automaticamente un file in formato .RST su Github partendo dal contenuto editato su Google doc.
↓
I file contenuti nello script da creare su Google doc
Lo script è costituito dai seguenti files che si trovano dentro il repository https://github.com/cirospat/GGeditor_script:
- conversion.html
- explicitMarkup.html
- generator.gs
- github.html
- properties.gs
- reSTMetadata.gs
- settings.html
- sidebar.html
- 程式碼.gs (程式碼 in cinese significa :guilabel:`codice`)
Per creare lo script su Google doc, andare su menu strumenti / < > editor di script. Nella pagina dello script copiare il codice dei 9 file di cui al repository https://github.com/cirospat/GGeditor_script dando lo stesso nome dei 9 file di cui sopra. Allo script così creato date il nome GGeditor.
Aggiornamento N.3 - 19_febbraio_2020
Messaggio “Bad Credential” (“Credenziali errate di Github”) su GGeditor. Github ha deprecato la sua API di autenticazione per “nome utente” e “password”, che è la causa principale del problema del messaggio “Bad Credential” ("Credenziali non valide").
La soluzione è facile, basta sostituire la password con cui si entra nell'account Github con il "token di accesso personale" quando si esegue il commit in GGEditor nel Google doc. I passi da seguire sono i seguenti:
- Vai alla pagina delle impostazioni in Github.com e crea un token di accesso personale in Github.com (How to by Github). Quindi copia il token di accesso personale negli appunti.
- Apri un documento Google e rimuovi tutte le credenziali archiviate precedentemente in GGEditor, quindi aggiungi un nuovo account Github con il token copiato come password.
Guarda i passi da compiere nelle schermate di Github:
Aggiornamento N. 4 - ottobre_2021
Messaggio di “non compilazione” del progetto su readthedocs.org e soluzione (news di fine ottobre 2021). Guarda anche la relativa issue su Github.
Da fine ottobre 2021 su readthedocs.org compare una non compilazione del progetto (build failed) legata alla versione di Sphinx. La soluzione è inserire nel file requirements.txt la seguente sintassi:
docutils<0.18
come di seguito illustrato.
1- avere un file denominato requirements.txt con il seguente codice:
sphinx-rtd-theme
sphinx
recommonmark
markdown
sphinx-markdown-tables
docutils<0.182- avere un file .readthedocs.yaml con il seguente codice:
version: 2
python:
install:
- requirements: requirements.txtAggiornamento N. 5 - maggio_2022
Fortunatamente il :guilabel:`componente aggiuntivo` per Google Doc GG editor è di nuovo disponibile nello store di Google per l’installazione. Vai al seguente link: https://workspace.google.com/u/1/marketplace/app/ggeditor/644886139871
Messaggio di errore “undefined”, soluzione
Nelle azioni di commit sul componente GGeditor potrebbe comparire un messaggio di “undefined” ed un messaggio di error in lingua taiwanese.
Ho aperto una issue (iapyeh/GGeditor#1) sul suo progetto Github e Hsin Yuan Yeh (autore di GGeditor) ha provveduto ad analizzare tempestivamente il problema ed ha fornito immediatamente una soluzione che è stata implementata nel codice sorgente di GGeditor.
Praticamente se dovesse capitare di leggere un messaggio “undefined” o un messaggio in lingua taiwanese del tipo ↓
La cosa da fare è:
andare in “Componenti aggiuntivi”, poi “GGeditor” e quindi su “Setting” dove si trova un tasto rosso di “Reset” che cancella tutte le informazioni di collegamento agli account Github e ai relativi file nel repository.
Tutto ritorna in ordine e funziona correttamente nella procedura di Commit da Google Doc a Github. Ovviamente bisogna ricollegare il componente aggiuntivo GGeditor all’account di Github per poter continuare a effettuare i commits. Grazie Hsin Yuan Yeh per questa tempestiva soluzione al problema.
Il componente aggiuntivo GGeditor rappresenta uno strumento molto utile e comodo in quanto i servizi di Google Drive oggi sono molto usati anche nelle Pubbliche Amministrazioni, oltre che dai privati, per la facilità d’uso e per la funzionalità di condivisione dei documenti in gruppo.
Il lavoro principale che svolge il componente aggiuntivo GGeditor è quello di trasformare il testo editato su un foglio di Google doc in un file con linguaggio .RST dentro il repository di Github. Github a sua volta permette la compilazione automatica dello stesso documento su Read the Docs in pagine HTML . Sembra una cosa difficile nella descrizione, ma se lo faccio io lo possono fare tutti, con un pizzico di pazienza e curiosità.
Breve video introduttivo (2’10”)
- Facile inizio per chi non ha dimestichezza con i file
RST, anche per chi non ha idea dei marcatori diRST. - Alimentato da Google Docs. Quasi la totalità di quello che vedi su Google Docs è quello che ottieni su Read the Docs. Lo stesso è per l'intero gruppo di lavoro.
- Un click per commissionare il lavoro sul repository di Github.
- Puoi vedere in anteprima il file
RSTgenerato dall'interno di Google Docs e scaricarlo nel tuo PC. - Supporta headings, bold, italic, hyperlink, subscript e superscript.
- Supporta note a margine, immagini, liste di articolo e tabelle.
- Supporta caratteri a larghezza intera (CKJ) nelle intestazioni e nelle tabelle.
- Supporta i link interni ai bookmarks, headings e le Google Docs tabelle native di contenuti (in document table of contents).
- Supporta i link relativi ai file
RSTgenerati dai Google Docs all'interno della stessa directory e sotto-directory Google Docs. - Supporta la tabella dei contenuti (cross-document table of content
(.. toctree::)) per fare generare l'indice a Read The Docs. - Supporta tutti gli stili di "admonitions" di Read The Docs.
- Supporta account multipli per compilare i file nei repository di diversi account Github.
- Supporta la conversione di tabelle con i tags
HTMLto let look-and-feel e la stessa cosa è possibile per i blogger.
.. toctree:: :maxdepth: 2 Home <https://googledocs.readthedocs.io>
.. toctree::
:maxdepth: 3
:caption: Indice
gdocs-rtd
tutorial
come-usarlo
tabelle
inserire_immagini_video
lavoro-github
lavoro-rtd
user-guide
hypothesis-partecipazione
sintassi-rst
sintassi-md
pubblicare-su-docs-italia
licenza
opendatasicilia
Tip
⇒ il contenuto di questa pagina che stai leggendo è editato in questo Google Doc ♞ … dai un occhiata per capire meglio come il testo di Google doc viene esposto su pagine HTML di :guilabel:`Read the Docs`
Please enable JavaScript to view the comments powered by Disqus.