Le funzioni su Google doc

Uno strumento per i principianti dei file ‘rST’

Se sei all’inizio della conoscenza dei file con sintassi RST (reStructuredText) e ti senti un po confuso sul come inserire i tuoi documenti sul portale di Read the Docs, questo strumento fa sicuramente per te. Con il componente aggiuntivo GGeditor per Google doc e questo piccolo tutorial tradotto in italiano dal tutorial originale, spero che potrai essere assistito nel realizzare il tuo lavoro in maniera facile e veloce. Se dopo averlo letto ti è rimasto qualche dubbio, beh.. contattami: cirospat@gmail.com.

Il plug-in di Google Doc, `GGeditor`

Per prima cosa da Google Doc si va su «Componenti aggiuntivi», si cerca e si installa il plug-in GGeditor

così si può cominciare ad usare il set di strumenti del menu che appare se clicchiamo su «componenti aggiuntivi», poi su GGeditor e poi ancora su «Show Markup Panel».

I settings dell’account Github

Dalla finestra “settings” è possibile agganciare il proprio account Github al plugin GGeditor in maniera tale che ogni volta che vogliamo commissionare un Google Doc su Gihub, cliccando su “Commit to Github” è possibile visualizzare l’elenco dei nostri repository su Github. Si seleziona quel repository che ci interessa sul quale intendiamo lavorare e si procede con l’azione di Commit del Google Doc.

L’operazione è molto semplice e alla portata di tutti perché non richiede particolari conoscenze specifiche.

Il ‘Markup Panel’ e le relative funzioni

Cliccando su su «Show Markup Panel» viene visualizzato questo pannello.

che ci consente di inserire sul documento in Google Doc:

Note colorate, personalizzabili nel titolo;
Codice da illustrare in una pagina HTML;
Tabella dell’indice dei contenuti (cioè il titolo delle pagine che compongono l’indice dei contenuti).

La costruzione dell’indice del documento

Dal Markup Panel di GGeditor è possibile costruire l’indice del documento da visionare sulle pagine HTML del progetto su Read the Docs.

Una volta inserita la maschera come di seguito rappresentato, basta editare il titolo delle altre pagine Google Doc che avete creato dentro la stessa directory di Google Drive. Sul file .rst che GGeditor crea verrà creato un indice che a sua volta verrà visualizzato su Read the Docs.

La procedura è di estrema facilità.

Dopo :caption: è possibile scrivere il nome che si vuole dare all’indice, o semplicemente scrivere “indice”. Ogni volta che si crea un nuovo Google Doc da agganciare all’indice basta riportare il titolo del Google Doc in questa maschera.

la sintassi da editare per creare l’indice è la seguente

.. toctree::
:maxdepth: 3
:caption: Indice
gdocs-rtd
tutorial
come-usarlo
lavoro-github
lavoro-rtd
user-guide
hypothesis-partecipazione
pubblicare-su-docs-italia
sintassi-rst
tabelle
licenza

Inline Markups - Marcatori in linea

Some inline reStructuredText markups can be used directly in the document. The table below shows the usage example of these inline markups.

In Google Docs document	Rendered in HTML page
A `single back-quote`	A single back-quote
A ``double back-quote``	A `double back-quote`
A \|replacement\| markup	A \|replacement\| markup

That is converted from the source content in document:

Please noted that if you manually put a substitution markup, you got to provide correct replacement markup manually too. Otherwise, the sphinx parser will raise exception.

Inserimento di blocchi di codice

blocco di codice senza righe numerate

#!/usr/bin/env python

"""
Twisted moved the C{twisted} hierarchy to the C{src} hierarchy, but C{git}
doesn't know how to track moves of directories, only files.  Therefore any
files added in branches after this move will be added into ./twisted/ and need
to be moved over into
"""

import os
from twisted.python.filepath import FilePath

here = FilePath(__file__).parent().parent()
fromPath = here.child("twisted")
toPath = here.child("src")

for fn in fromPath.walk():
    if fn.isfile():
        os.system("git mv {it} src/{it}"
                  .format(it="/".join(fn.segmentsFrom(here))))

os.system('git clean -fd')

def outer(x):
def indent_start(x):
    go start start
    go start end

def end(y):
    go end start
    go end end

blocco di codice con righe numerate

#!/usr/bin/env python

"""
Twisted moved the C{twisted} hierarchy to the C{src} hierarchy, but C{git}
doesn't know how to track moves of directories, only files.  Therefore any
files added in branches after this move will be added into ./twisted/ and need
to be moved over into
"""

import os
from twisted.python.filepath import FilePath

here = FilePath(__file__).parent().parent()
fromPath = here.child("twisted")
toPath = here.child("src")

for fn in fromPath.walk():
    if fn.isfile():
        os.system("git mv {it} src/{it}"
                  .format(it="/".join(fn.segmentsFrom(here))))

os.system('git clean -fd')

def outer(x):
def indent_start(x):
    go start start
    go start end

def end(y):
    go end start
    go end end

Visualizzazione di messaggi di errore: ‘undefined’ o messaggio ‘in lingua taiwanese’. Come risolverli.

Se durante la procedura di commit dal Google doc a Github viene visualizzato ripetutamente un messaggio di “undefined” o un messaggio di error in lingua taiwanese, che non permette di portare a termine il commit, l’azione da compiere è la seguente:

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. In effetti quello che avviene è una pulizia della cache, è come se si fosse appena installato il componente aggiuntivo GGeditor sul Google doc.

In questa parte del tutorial vengono illustrati anche i messaggi che possono apparire nel caso descritto.

Inserire note colorate di vario tipo

Attraverso il tasto ‘Show markup panel’ è possibile inserire nel doc, e quindi nel progetto “read the docs” alcuni box per attirare l’attenzione del lettore su alcuni contenuti della pubblicazione. Eccoli di seguito elencati.

Attenzione

(content of Attention)

Attenzione

(content of Caution)

Avvertimento

(content of Warning)

Pericolo

(content of Danger)

Errore

(content of Error)

Suggerimento

(content of Hint)

Importante

(content of Important)

Suggerimento

(content of Tip)

Nota

(content of Note)

Vedi anche

(content of See also)

Change-me

(content of Change-me)

Inserire in alcune pagine la possibilità di far lasciare commenti

In alcune pagine HTML del progetto Read the Docs, l’editore del documento da pubblicare online potrebbe avere l’esigenza di raccogliere commenti.

In questo caso, cioè solo quando questa esigenza dei commenti è relativa ad alcune pagine HTML del documento e non in tutte, viene in aiuto il servizio online di Disqus. Si procede innanzitutto creando un account in questo servizio e successivamente si crea un progetto, fornendo un URL a cui agganciare il servizio di Disqus. Lo stesso Disqus fornisce un codice HTML che bisogna copiare e incollare dentro un box HTML all’interno del Google doc nel quale si desidera far lasciare commenti.

Il codice Disqus di questa pagina ad esempio è il seguente ed è editato alla fine di questo Google doc che genera la pagina HTML sul progetto di Read the Docs:

<script id="dsq-count-scr" src="//guida-readthedocs.disqus.com/count.js" async></script>

<div id="disqus_thread"></div>
<script>

/**
*  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR PLATFORM OR CMS.
*  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: https://disqus.com/admin/universalcode/#configuration-variables*/
/*

var disqus_config = function () {
this.page.url = PAGE_URL;  // Replace PAGE_URL with your page's canonical URL variable
this.page.identifier = PAGE_IDENTIFIER; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
};
*/
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = 'https://guida-readthedocs.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>

Altre (tante) utili funzioni di `GGeditor`

Inline Markups, Table, Image, Conversion.

Qui e qui (esempi) sono descritte molte funzioni che possono essere attivate con GGeditor, quale per esempio quella della conversione del contenuto del nostro Google Doc in un file formato RST, quindi con la sintassi tipica di questo linguaggio.

Conversione di testo da Google doc a file .RST per il download

Il componente aggiuntivo GGeditor permette anche la funzione di conversione del testo in linguaggio .RST (vedi link per le funzioni complete di conversione). Praticamente è possibile, tramite una finestra dedicata, far convertire a GGeditor testo direttamente in linguaggio .RST. Si può convertire tutto il testo, una parte, o ad esempio una tabella. Ci sono delle regole di conversione già illustrate nella stessa finestra denominata “Conversion”. Una volta convertito il testo appare un messaggio di avvenuta conversione ed è possibile effettuare il download del testo convertito in formato .RST oppure selezionarlo e copiarlo in un editor testuale per un ulteriore riuso.