Docs Italia beta

Capitolo 1 - Caricare il progetto editoriale su Github (lavorando online su Github)

(Modalità per lavorare su Github online, adatto per chi ha poca familiarità con gli strumenti di controllo versione).


Si inizia con lo «starter kit»

Questa http://guida-docs-italia.readthedocs.io/it/latest/index/starter-kit.html è la versione che dovremmo usare come modello di base, proposto dal Team Trasformazione Digitale, per riprodurre il nostro documento su Read the Docs.

Cliccando su scarica lo Starter kit si viene rimandati al repository del progetto sulla piattaforma Github, cioè qui https://github.com/italia/docs-italia-starter-kit.

../_images/img3.png

Importare il progetto dello «starter kit» nel proprio account Github

L’azione da avviare ora è l’importazione del progetto dello starter kit nel proprio account Github, dando un nome al progetto a cui si vuole lavorare. Quindi andare dentro le directory del progetto per personalizzare i contenuti e i metadati del nostro progetto. Ora vedremo come.


Nel progetto Github abbiamo

  • una directory repo-configurazione che contiene due file dove dobbiamo inserire un po di metadati sul progetto che andiamo a pubblicare, come: titolo, descrizione, tags, sito web ente che pubblica il documento;
  • una directory repo-documento dove si trovano i file:
    • conf.py dove dobbiamo inserire il titolo del nostro documento che vogliamo visualizzare successivamente su Read the Docs. Importante: su settings_project_name usare un titolo non molto lungo e non usare parole accentate come à,è,ì,ò,ù, scegliendo il simbolo ' per accentare le vocali. Altra cosa importante settings_basename = “titolo-documento” cioè su settings_basename e settings_file_name usare parole delimitate dal simbolo - (trattino).
    • document_settings.yml dove dobbiamo inserire un po di metadati sul progetto che andiamo a pubblicare: titolo, descrizione, tags, sito web ente che pubblica il documento;
    • requirements.txt che non dobbiamo toccare perché contiene l’istruzione che permette di visualizzare il progetto che stiamo andando a creare all’interno del template di Docs Italia, dove si trovano anche tutti gli altri documenti pubblicati dal Team Trasformazione Digitale, cioè https://docs.developers.italia.it/,
  • un file AUTHORS dove va scritto il nome dell’ente che pubblica il documento e della persona che ha lavorato;
  • README.md un file dove descriviamo brevemente il nostro progetto di pubblicazione del documento;
  • LICENSE un file dove andremo ad inserire il tipo di licenza adottata per pubblicare il nostro documento che verrà visualizzato su Read the Docs;
  • _docs una directory che contiene le pagine del nostro documento, cioè i contenuti veri e propri, che possono essere: testo, immagini, tabelle. Questa directory contiene file di tipo RST (reStructuredText). Nel paragrafo che segue approfondiremo questo tipo di file;
  • _img: una la directory dove andare a caricare le immagini che si vuole vengano visualizzate poi sulle pagine html di Read the Docs. E” importante nel testo dei file RST fissare le immagini (dentro il testo) usando la seguente sintassi:
.. figure:: _img/immagine1.png
Quando si vuole inserire una didascalia nell’immagine, è importante dopo aver scritto
.. figure:: _img/immagine1.png
andare due volte a capo
e lasciare tre spazi vuoti prima di inserire il testo

La directory _docs e i file RST

La directory _docs contiene i file che sono le pagine del nostro documento (e i relativi contenuti) che visualizzeremo sulle pagine html di Read the Docs. Questi file sono di tipo RST (reStructuredText), un linguaggio di programmazione molto semplice per sintassi utilizzata.

Un ottima guida alla sintassi usata dal linguaggio RST è questa http://docutils.sourceforge.net/docs/user/rst/quickref.html dalla quale è possibile apprendere la sintassi corretta per le nostre necessità di pubblicazione del testo (e immagini, tabelle) nella pagina.

Come Scrivere in formato ReStructuredText

Un buon editor RST online WYSIWYG (What You See Is What You Get: quello che vedi è quello che è) è http://rst.ninjs.org/ dove è possibile scrivere e controllare lateralmente il risultato che si otterrà.

../_images/4bis.PNG

Alcune sintassi del linguaggio RST per gli usi più comuni di scrittura:

Title
======

per il titolo capitolo


Subtitle
--------

per il titolo paragrafo


**testo marcato**

per il testo marcato


*testo in italico*

per il testo in italico


.. figure:: _image/immagine1.png
per inserire un’immagine
(il titolo del file immagine è ad esempio immagine1.png. Il file dovrà essere caricato in una directory denominata img, è consigliabile caricare questa director contenente le immagini dentro la directory principale del progetto Github)

`link <https://www.link.it>`_

per inserire un collegamento ipertestuale. Per editare il carattere ` è necessario usare contemporaneamente i tasti Alt+96 da Windows


.. important::

per inserire testo, se volete inserire una nota colorata all’interno del testo nella pagina, verrà visualizzato come di seguito:

../_images/img4.png
quando si usa questa nota colorata è importante dopo aver scritto
.. important::
andare due volte a capo
e lasciare tre spazi vuoti prima di scrivere il testo

Nota sui file RST

Importante

Guardando i file RST di qualsiasi pagina su Github (per esempio di questa pagina che state leggendo) capirete immediatamente come editare la sintassi corretta per le vostre necessità di rappresentazione di testo, immagini, tabelle, note, ecc.

Per tutte le necessità specifiche di editing nel documento (es.: tabelle) vedere questo elenco di strumenti.


Downloads
pdf
htmlzip
epub
torna all'inizio dei contenuti