User-guide (gli step operativi)

L’importanza della formattazione corretta del testo su Google doc

La formattazione corretta nel testo del Google doc è la cosa più importante da seguire. Appare molto importante rispettare il “titolo”, il “sottotitolo”, l’”intestazione 1”, l’”intestazione 2”, l’”intestazione 3”, e così via. Il resto del testo deve essere formattato come “testo normale”.

Se non rispettate le regole (facili) della formattazione, il testo in HTML nel progetto Read the Docs ne risentirà, non permettendo una facile lettura.


Consegnare i file da Google Doc a Github

Una volta effettuato l’accesso a Github (dall’interno di Google Doc) e terminata la compilazione del testo su Google Doc si passa all’operazione di commissionamento del file a Github. La finestra di GGeditor guida alla creazione del file di Google Doc dentro il progetto di Github. La procedura guidata dalla finestra di GGeditor è abbastanza intuitiva.

IMG1

Una volta cliccato OK per il commit s Github, verrà creato un file RST sulla cartella «doc» dentro il progetto di Github.

Attenzione

E” importante sapere che prima di effettuare questa operazione illustrata nella figura di sopra, è necessario creare il nome del progetto su Github, in maniera tale che quando seguiamo le operazioni della figura (dalla 1 alla 5) indichiamo a Github il nome del progetto nel quale GGeditor deve andare a creare il file che prende lo stesso nome del titolo del Google Doc, in più GGeditor provvede ad aggiungere il suffisso «.rst» dentro la directory madre di Github.

If you want to commit to a new file. Please

  1. Navigate to the folder where the new file would be

  2. Click on the “New File” item

  3. Give the file name to create. The name will be suffix with “.rst” automatically.

Committing

L’azione di “committing” rappresenta il trasferimento del contenuto del Google doc al file in formato .rst dentro il repository di Github. In questo trasferimento il contenuto del Google doc viene trasformato automaticamente in linguaggio .rst. Questo è il lavoro più prezioso che svolge il componente aggiuntivo GGeditor!

IMG2

[la finestra che ci indica il Google Doc che dobbiamo inviare in una cartella («.doc») del progetto su Github]

IMG3Se solo il testo è stato modificato nel Doc, puoi evitare di flaggare il tasto “Commit images” per escludere il commit a Github delle immagini, questo porterà a una riduzione dei tempi dell’effettuazione del processo di commit.

Nota

GGeditor posizionerà i file immagini presenti nel Google doc sulla cartella static del progetto su Github. Se nel Google doc vengono modificate immagini o anche vengono cancellate o sostituite, ogni volta bisogna cliccare sul componente aggiuntivo GGeditor e quindi su «commit images».

Attenzione

Se avete molte immagini in un Doc, il che significa molte immagini da caricare su Github tramite GGeditor, potrebbe succedere di incontrare situazioni di immagini rotte nelle corrispondenti pagine HTML di Read the Docs. Questo perché il processo di rigenerazione delle pagine HTML è ancora in corso, non dovete -quindi- preoccuparvi. In questo caso dovete aspettare ancora un po che finisca il processo di costruzione delle stesse pagine su Read the Docs. Oppure se le immagini non compaiono ancora nelle pagine HTML, un ultima cosa da fare è andare nella pagina «Administration» del progetto su Read the Docs e cliccare su «Saving«.

Comunque se vedi immagini vecchie e non rispondenti all’ultima versione del Doc, elimina la cache del browser o controlla sul repository di Github la corrispondenza delle foto del Google doc con quelle nella cartella static su Github.

Vedi anche

In merito all’inserimento delle immagini nel Google doc, vedere anche il paragrafo “inserimento di video, immagini, ed embedding nel testo”.

Limitazioni

Funzioni non supportate da Google Doc sui file reST:

  • Comments. This is not supported by the reST1.

  • Drawing objects. Because there is no API to get it as an image.

  • List styles. The list style is defined by the CSS settings in the html page.

  • Math equations. Because this is no API to get it as an image.

  • Multi-columns. This is not supported by the reST.

  • Page break. This is not able to apply to a html page.

  • Page header and page footer. This is not supported by the reST.

  • Page numbering. This is not able to apply to a html page.

  • Internal link to heading does not work. Currently there is no API to identifiy the target heading element. Please use “Bookmark“ instead.

  • Bold and italic styles in footnote content does not exposed by Doc’s API. Which means bold and italic text is rendered as normal text in footnote content.

Strumenti per i più esperti

Conversione

Per la conversione del testo da Google Doc al formato RST (e anche previsto il download del file RST) si fa riferimento a questo paragrafo del tutorial di GGeditor.

Api Docs

Per API document for a Python module si fa riferimento a questo paragrafo del tutorial di GGeditor.

Backend

Documentazione specificata nel Google Python Style Guide. Si fa riferimento a questo paragrafo del tutorial di GGeditor.

Footnotes

1

per i commenti usa il servizio di hypothes.is illustrato in questa pagina de tutorial