Tools per la realizzazione della documentazione¶

Editor di github¶

L'impostazione predefinita di github mostra l'icona della penna in ogni pagina, per aprire in maniera facile l'editor online.

penna per la modifica

L'URL per editare la pagina tooling nella sezione about è https://github.com/asti-co/doc/edit/main/about/tooling.md. Notare che l'URL è .com.

La pagina permette di modificare il contenuto inserendo codice markdown. edit in git

Selezionando il tab Preview è possibile vedere la pagina con il contenuto trasformato nel formato finale, come sarà poi visibile agli utenti.
Su questa pagina è possibile indicare un commento che descrive le modifiche fatte e pubblicare la pagina cliccando sul tasto Commit changes

edit in git

Una volta pubblicata, la pagina viene mostrata in formato read-only di github, con l'icona della matita per riaprire l'editor.

edit in git

Le pagine modificate non saranno immediatamente visibili in quanto vanno dapprima trasformate. Vedi la sezione in basso per controllare il processo di pubblicazione.

Editor Visual Studio Code¶

Cambiando l'URL di github da .com a .dev abilita l'utilizzo online dell'editor MicroSoft Visual Studio Code (https://github.dev/asti-co/doc/).

Non tutte le opzioni nella colonna di sinistra sono attivi nella versione online, ma quelle utili lo sono!

La prima in alto mostra la lista delle cartelle e dei file, permettendo la navigazione tra le pagine e l'apertura di uno a più file in editor in tab separati.

Le due icone in alto a destra permettono di visualizzare l'anteprima della pagina, rispettivamente aprire una seconda finestra di editing.

vscode1

L'editor mostra il codice markdown, con le parole chiave, titoli, link, ecc. rappresentati in colori e font diversi.

vscode2

La terza opzione nella colonna di sinistra permette la pubblicazione del codice. L'icona mostra il numero di file modificati, mentre la seconda colonna mostra i file modificati.
Sopra la lista di file modificati è possibile indicare un commento che descrive le modifiche fatte e pubblicare la pagina cliccando sull'icona del visto in alto.

vscode3

Le pagine modificate non saranno immediatamente visibili in quanto vanno dapprima trasformate. Vedi la sezione in basso per controllare il processo di pubblicazione.

Controllo del processo di pubblicazione¶

Selezionando la scheda Actions permette di controllare i processi di compilazione delle pagine.

build1

Il processo è completamente automatico ed è suddiviso in due fasi.

build2

Le nuove pagine saranno pronte e visibili a tutti quando entrambe le fasi mostreranno lo stato completato, simboleggiato da un visto verde.
In caso di errori, l'icone diventa un punto rosso. Cliccando sull'azione relativa permette di accedere ai log e ai messaggi di errore, utili per capirne la causa.

build3

Sviluppo in locale¶

Creare la documentazione localmente sul proprio PC permette modifiche più ampie con un controllo preciso del risultato finale prima della sua pubblicazione.
I tool richiesti sono:

git per la gestione delle versioni dei file
vscode o altro editor di testo
python per la trasformazione dei file

git¶

Git è un programma per la gestione di file condivisi che permette la collaborazione di varie persone nella creazione e nell'aggiornamento dei file, mantenendo tutte le modifiche come versioni dei file.

Installa git scaricandolo dal sito ufficiale git-scm.com/downloads
Nota: per Windows scegli Standalone installer
Configura git
1. Apri il file .gitconfig nella cartella utente con un editor di testo.
  Nota: il file è nascosto, per cui abilita la visione dei file nascosti.
  Nota: se il file non esiste, crealo.
2. Imposta il nome e indirizzo email
  Contenuto file
```
[user]
    name = Sandro Corsi
    email = sandro.corsi@bluewin.ch
```
Apri un terminale con il comando cmd.exe di Windows

Verifica che la configurazione sia corretta
Comando

git config --global -l

Output

user.name=Sandro Corsi
user.email=sandro.corsi@bluewin.ch

Crea una cartella per la documentazione ASTI
```
mkdir c:\DocAsti
```
Spostati nella cartella appena creata
```
cd c:\DocAsti
```

Copia tutta la documentazione in locale.

git clone https://github.com/asti-co/doc.git

A questo punto hai tutta la documentazione sul tuo PC. Puoi editare i file .md con qualsiasi editor di testo (notepad, notepad++, ultraedit, VSCode ecc. ma NON programmi come Word).
I file sono nelle cartelle sotto C:\DocAsti\doc\docs

Usa i seguenti comandi per gestire i file da command line

Prima di cominciare a lavorare, aggiorna i file sul PC prendendo l'ultima versione disponibile sul server
1. Apri un terminale con il comando cmd.exe di Windows
2. Spostati nella cartella della documentazione
```
cd c:\DocAsti\doc
```
3. Aggiorna i file locali prendendo l'ultima versione dal server
```
git pull
```
Dopo aver modificati dei file, pubblicali sul server
1. Apri un terminale con il comando cmd.exe di Windows
2. Spostati nella cartella della documentazione
```
cd c:\DocAsti\doc
```
3. Identifica tutti i file modificati
  Nota: occhio al punto finale... è necessario!
```
git add .
```
4. Aggiungi un commento che descrive le modifiche fatte (corto, max 50 caratteri)
```
git commit -m "la descrizione di quel che hai fatto"
```
5. Manda le modifiche al server
```
git push
```
6. Aggiorna i file locali prendendo l'ultima versione dal server
```
git pull
```

VSCode¶

Puoi usare qualsiasi editor di testo.
L'editor VSCode è disponibile gratuitamente su Windows, Linux e MacOS ed ha tanti plugin a disposizione, tra cui anche quelli per la gestione integrata di git e delle pagine markdown.

Scarica VSCode
Di regola è consigliato lanciare VSCode con code ., configurazione di default su Windows e Linux.
Per MacOS, seguire queste istruzioni
In VSCode apri la cartella della documentazione ASTI (in File > Open Folder...), secondo l'esempio C:\DocAsti\doc
Nota: se è attivo il plugin di git sarà possibile eseguire i comandi descritti sopra direttamente dal tool.
Utilizza VSCode in locale come quello online (vedi la descrizione sopra)

Crea localmente¶

Per la generazione delle pagine su Linux/MaxOS

Apri un terminale con il comando cmd.exe di Windows
Spostati nella cartella della documentazione
```
cd c:\DocAsti\doc
```
Inizialmente (solo una volta) inizializza il sistema
```
make venv serve
```
In seguito, usa unicamente questo comando
```
make serve
```
1. Controlla l'output per vedere se ci sono errori.
  Ad esempio, il tool mostra i link a pagine non esistenti.
2. Finiti i controlli viene mostrato il messaggio seguente
```
Serving on http://127.0.0.1:8000/
```
Apri l'indirizzo indicato http://127.0.0.1:8000/ in un browser internet (Firefox, Chrome, ecc.)
Nota: il sistema si accorge autonomamente del cambiamento del contenuto delle pagine e ogni volta che salvi un file questo viene compilato e la pagina è aggiornata nel browser.

Per la generazione delle pagine in Windows

La seguente descrizione usa comandi python da lanciare in un terminale di Windows.

Installa Python3 da https://www.python.org/downloads/
Apri un terminale con il comando cmd.exe di Windows
Spostati nella cartella della documentazione
```
cd c:\DocAsti\doc
```

Inizialmente (solo una volta) inizializza il sistema

Crea l'ambiente
```
python -m venv env
```
Inizializza il sistema
```
env\Scripts\activate.bat
```

Installa le librerie

python -m pip install --upgrade pip setuptools wheel

Installa/aggiorna altri requisiti

python -m pip install --upgrade -r requirements.txt

In seguito, usa unicamente questi comandi
1. Inizializza il sistema
```
env\Scripts\activate.bat
```
2. Lancia il server
```
mkdocs serve --livereload -a 127.0.0.1:8000
```
3. Controlla l'output per vedere se ci sono errori.
  Ad esempio, il tool mostra i link a pagine non esistenti.
  
  Nota: Se questo comando lancia delle eccezioni (lunghi messaggi d'errore) devi utilizzare la procedure con il Windows Subsystem for Linux.
4. Finiti i controlli viene mostrato il messaggio seguente
```
Serving on http://127.0.0.1:8000/
```
Apri l'indirizzo indicato http://127.0.0.1:8000/ in un browser internet (Firefox, Chrome, ecc.)
Nota: il sistema si accorge autonomamente del cambiamento del contenuto delle pagine e ogni volta che salvi un file questo viene compilato e la pagina è aggiornata nel browser.

Per la generazione delle pagine in Windows col Subsystem for Linux

Questa soluzione utilizza il Windows Subsystem for Linux per eseguire alcuni comandi in Windows ed alcuni in Linux.

Installa e configura WSL (solo una volta)
1. Apri un terminale con il comando cmd.exe di Windows
2. Installa il Windows Subsystem for Linux (WSL) con Ubuntu (vedi la documentazione Microsoft)
```
wsl --install
```
3. Apri il terminale di WSL con il comando wsl.exe
4. Inizializza il sistema
```
# assicurati che il sistema sia aggiornato
sudo apt-get update
sudo apt-get ugrade

# assicurati che pyhton, pip e venv siano installati
sudo apt install python3
sudo apt install python3-pip
sudo apt install python3.8-venv
```
5. Vai nella cartella della documentazione ASTI
  Nota: il disco C: è accessibile in WSL come cartella /mnt/c
```
cd /mnt/c/DocAsti/doc
```
6. Crea l'ambiente e lancia il server
```
make venv serve
```
In seguito, usa unicamente questi comandi
1. Apri il terminale di WSL con il comando wsl.exe
2. Vai nella cartella della documentazione ASTI
  Nota: il disco C: è accessibile in WSL come cartella /mnt/c
```
cd /mnt/c/DocAsti/doc
```
3. Lancia il server
```
make serve
```
  1. Controlla l'output per vedere se ci sono errori.
    Ad esempio, il tool mostra i link a pagine non esistenti.
  2. Finiti i controlli viene mostrato il messaggio seguente
```
Serving on http://127.0.0.1:8000/
```
Apri l'indirizzo indicato http://127.0.0.1:8000/ in un browser internet (Firefox, Chrome, ecc.)
Nota: il sistema si accorge autonomamente del cambiamento del contenuto delle pagine e ogni volta che salvi un file questo viene compilato e la pagina è aggiornata nel browser.