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.
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.
Una volta cliccato OK per il commit s Github, verrà creato un file RST sulla cartella "doc" dentro il progetto di Github.
Attention!
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
- Navigate to the folder where the new file would be
- Click on the “New File” item
- Give the file name to create. The name will be suffix with “.rst” automatically.
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!
[la finestra che ci indica il Google Doc che dobbiamo inviare in una cartella (".doc") del progetto su Github]
Se 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.
Note
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".
Attention!
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.
.. seealso::
In merito all’inserimento delle immagini nel Google doc, vedere anche il paragrafo “\ |LINK1|\ ”.
Funzioni non supportate da Google Doc sui file reST:
- Comments. This is not supported by the reST[1].
- 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.
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.
Per API document for a Python module si fa riferimento a questo paragrafo del tutorial di GGeditor.
Documentazione specificata nel Google Python Style Guide. Si fa riferimento a questo paragrafo del tutorial di GGeditor.
Please enable JavaScript to view the comments powered by Disqus.
Footnotes
| [1] | per i commenti usa il servizio di hypothes.is illustrato in questa pagina de tutorial |