Da Google Doc con «GGeditor» → via GitHub → a Read-the-Docs

Tutorial undefined

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.


Vantaggi dell’uso di “Read the Docs”

L’uso di Read the Docs come piattaforma di pubblicazione di documenti online ha i seguenti vantaggi rispetto al formato 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 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 PDF che EPUB oltre che HTML.


Changelog

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 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:

  1. 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.

  2. 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:

IMG1


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:

1sphinx-rtd-theme
2sphinx
3recommonmark
4markdown
5sphinx-markdown-tables
6docutils<0.18

2- avere un file .readthedocs.yaml con il seguente codice:

1version: 2
2python:
3   install:
4   - requirements: requirements.txt

Aggiornamento N. 5 - maggio_2022

Fortunatamente il 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 (https://github.com/iapyeh/GGeditor/issues/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 ↓

IMG2

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.

IMG3

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.


L’utilità di GGeditor per i progetti di documentazione online

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”)


Le principali funzioni e punti di forza di GGeditor

  • Facile inizio per chi non ha dimestichezza con i file RST, anche per chi non ha idea dei marcatori di RST.

  • 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 RST generato 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 RST generati 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 HTML to let look-and-feel e la stessa cosa è possibile per i blogger.


Indice

Suggerimento

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 Read the Docs