Da Google Doc direttamente a Read the Docs con GGeditor

Passando automaticamente da Github!

{tutorial}

undefined

Le spiegazioni contenute in questo documento rappresentano una via piuttosto facile per migliorare la qualità dei documenti pubblicati sul web e sono la traduzione in italiano del tutorial GGeditor. Fondamentalmente il tutorial spiega come usare lo strumento di Google doc, ed un componente aggiuntivo, per pubblicare documenti con lo stile di Read the Docs e con il design di Docs Italia.

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 di 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 che HTML.


GGeditor, un componente aggiuntivo di Google doc

GGeditor è un componente plugin che si installa direttamente da Google Doc (della suite di Google Drive).

Aggiornamento gennaio_2020

Se da Google doc cliccando su “installa componente aggiuntivo” non trovate “GGeditor” - cercando sul Marketplace di Google (capita dall’agosto 2019 per una ridefinizione dei termini d’uso di Google) - potete cliccare direttamente sul link del componente aggiuntivo GGeditor.

Tuttavia al link - già dal 2019 - non è possibile più fare l’installazione del componente aggiuntivo GGeditor, quindi passate alla procedura del successivo aggiornamento del 14_febbraio_2020.


Aggiornamento 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 dare il nome GGeditor.


Aggiornamento 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 (aggiornamento 19_feb_2020)


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 posso assicurare che se lo faccio io lo possono fare tutti, con un po di pazienza e curiosità.

Breve video introduttivo (2’10”)


Le principali funzioni e punti di forza di GGeditor sono

  • 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