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: [email protected].
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".
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.
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).
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
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.
#!/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
#!/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.
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.
Attention!
(content of Attention)
Caution!
(content of Caution)
Warning
(content of Warning)
!DANGER!
(content of Danger)
Error
(content of Error)
Hint
(content of Hint)
Important
(content of Important)
Tip
(content of Tip)
Note
(content of Note)
.. seealso:: (content of See also)
Change-me
(content of Change-me)
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>
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.
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.
Please enable JavaScript to view the comments powered by Disqus.