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.

Fig. 3 la guida dello starter kit

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.

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

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à.

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

`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:

Nota sui file RST¶

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