----------------------
STRUTTURA DEL PROGETTO
----------------------

build
		cartella dedicata all'output del compilatore,
		dove si trovano i file html e pdf aggiornati
		dopo aver eseguito il comando di compilazione
install
		cartella dove si trovano i file per l'installazione o l'aggiornamento
		di sphinx e tutto l'ambiente di sviluppo del manuale
make
		cartella dove si trovano i make file e i comandi batch per la compilazione
		(semplificano i comandi di compilazione)
misc
		(miscellaneous) cartella con delle utilità varie e non indispensabili
source
		cartella con tutti i codici sorgenti, incluse le figure e le estensioni di sphinx
.gitignore
		file che elenca le estensioni che vengono ignorate da git
...code-workspace
		file di configurazione di visual studio code per l'apertura automatica del progetto
README
		file informativo sul progetto

source/_ext
		cartella con le estensioni personalizzate di sphinx
		tra cui quelle per creare le tabelle di parametri e variabili
		e il file excel per generare il dizionario con parametri e variabili
source/_static
		cartella con tutte i file (figure, csv, ...) che servono in fase di compilazione
		i riferienti ai file all'interno di _static dentro i sorgenti si possono fare
		con un riferimento assoluto che comincia con /_static/...
		questo rende più robusto il codice, che non dipende più dal percorso relativo
		tra i file sorgente e le figure
source/locale
		cartella inerente alla traduzione della documentazione in altre lingue
		contiene i file .po ("mappe" che contengono la corrispondenza
		tra le stringhe originali e le stringhe tradotte)
source/contents
		cartella che racchiude tutti i file sorgenti della documentazione
		è organizzata in sottocartelle che ricalcano la suddivisione in parti/capitoli/sezioni
source/conf.py
		file di configurazione di tutto il progetto
source/index.rst
		indice principale del progetto da cui vengono richiamati tutti gli altri indici e file sorgenti
source/_templates.rst
		cartella con file che servono per configurazioni speciali


--------------------------------------------------------
INSTALLAZIONE/predisposizione dell'ambiente di sviluppo:
--------------------------------------------------------

		LEGENDA:
		-#- OBBLIGATORI
		-*- OBBLIGATORI SOLO PER VERSIONE PDF (comando $ make latexpdf)
		--- FACOLTATIVI/consigliati

--- installare VisualStudioCode
    	+ estensione per rst (ad esempio reStructuredText oppure reStructuredText Syntax highlighting) 
		+ estensione per csv (ad esempio Edit csv)
		+ usare CTRL+SHIFT+F per cercare e sostituire parole in tutto il progetto
-#- installare Python dal sito ufficiale
		+ selezionare "add python.exe to PATH" durante la fase di installazione 
-*- installare Inkscape
		+ selezionare "Add Inkscape to the system PATH for all users" durante la fase di installazione
    	(serve per convertire automaticamente svg in pdf per latex che non accetta i file svg)
    	(per altre info: https://pypi.org/project/sphinxcontrib-svg2pdfconverter/ )
-*- installare MikTeX opzioni di default
		+ selezionare "installa pacchetti al volo: YES" durante la fase di installazione
    	Poi eseguire un aggiornamento dei pacchetti da interfaccia (Start -> MikTeX -> check for updates -> update)
-*- installare Perl (serve per far funzionare miktex)
		scaricare e installare la versione MSI da https://strawberryperl.com/
-*- installare i font Dejavu
		decomprimere il file install/DejaVu_font.7z,
		selezionare tutti i file, tasto destro -> install.
-#- eseguire install/install_pip_update.bat
-#- eseguire install/install_requirements.bat (così si installeranno tutti i pacchetti elencati dentro il file requirements.txt)
--- installare Microsoft’s HTML Help Workshop compiler: https://www.helpandmanual.com/downloads_mscomp.html
		inserire il percorso di hhc.exe (dentro Program Files (x86) ) nelle variabili di sistema
    	hhc serve per compilare i file .hhp in file .chm
		(chm = Compiled HTML Help, file che può essere navigato e visualizzato tramite il "Microsoft HTML Help Viewer")
--- installare Poedit per la gestione dei file .po (per la traduzione del documento in altre lingue)
-#- installare libreoffice draw nel caso in cui si vogliano editare gli schemi a blocchi

------------------------------------------
COMANDI UTILI da utilizzare nel terminale:
------------------------------------------

	Dalla cartella "make"

		$ .\make html

		$ .\make latexpdf

		$ sphinx-autobuild ../source ../build/html --open-browser --port 0	
	
	o dalla cartella di progetto (quella che contiene la cartella make)

		$ sphinx-autobuild ./source ./build/html --open-browser --port 0	

	ALTERNATIVA: utilizzare i file bat dentro la cartella "make"
		- doppio click nel file make_pdf.bat per ottenere la versione pdf
		- doppio click nel file make_html.bat per ottenere la versione html
		- doppio click nel file autobuild.bat per avviare sphinx-autobuild

	--> La versione pdf si troverà nella cartella build/latex
	--> La versione html si troverà nella cartela build/html

	Nota:
		sphinx-autobuild è molto comodo durante le fasi di modifica dei contenuti
		ricompila automaticamente la versione html ogni volta che si salvano delle modifiche
		e aggiorna una pagina web con l'html aggiornato
		(la pagina web è quella che si apre automaticamente quando si esegue il comando)


---------------------
ESTENSIONI DI SPHINX:
---------------------

Sphinx permette di programmare funzioni aggiuntive per personalizzare il comportamento e semplificare il codice.
Si chiamano estensioni di sphinx e sono contenute nella cartella _ext
Sono state utilizzate per la creazione automatica di tutte le tabelle di parametri e variabili all'interno del capitiolo Parametri e variabili
Questo ha consentito anche di implementare un meccanismo automatico di verifica dei parametri.
Il principio di funzionamento è il seguente:
- il file INV_rXX.xls è lo stesso utilizzato da Alexis per configurare il codice del firmware,
  dove XX è la versione del firmware.
  Ciascuna versione del firmware ha il proprio file excel
  con all'interno tutti e solo i parametri del firmware
- il file excel ha al suo interno una macro che produce un dizionario python con tutti i parametri e variabili
- il dizionario python è utilizzato dall'estensione di sphinx

Di conseguenza:
- se Alexis cambia il nome di un parametro/variabile oppure lo elimina, o ne aggiunge uno nuovo,
  sarà possibile accorgersene senza dover revisionare tutto l'intero manuale. 

Nota:
- non si è riusciti a inserire le label all'interno dell'estensione per parametri,
  il che ha reso necessaria l'inserimento manuale della label.
  Fintanto che non si troverà una soluzione migliore, utilizzare la seguente convenzione,
  dove nel caso dei parametri "normali" la label è posta sul titolo del paragrafo omonimo del parametro,
  mentre nel caso dei parametri a bit (che non hanno un paragrafo dedicato) la label è di tipo "inline" con la sintassi _`...`.
  Purtroppo questa soluzione duplica il codice con il nome del parametro,
  con possibilità di errori se non si modifica allo stesso modo in entrambi i punti

Esempio per parametro normale:

	.. _[qui_inserire_il_nome_del_parametro]:

	[qui_inserire_il_nome_del_parametro]
	-----------------------------

	.. table-param::
	:params: [qui_inserire_il_nome_del_parametro]

	[Qui inserire la descrizione del parametro]


Esempio per un singolo bit di un parametro:

	.. table_bitpar::
	:param: [qui_inserire_il_nome_del_parametro]
	:bitname: [qui_inserire_il_nome_del_bit]

	_`[qui_inserire_il_nome_del_bit]` [Qui inserire la descrizione del bit]

ATTENZIONE: 
	le label devono essere uniche all'interno di tutto il progetto.
	Mentre parametri e variabili hanno nomi univoci all'interno del codice,
	i nomi dei bit possono essere uguali tra parametri diversi.
	Grazie al fatto che i nomi sono fatti in modo coerente,
	se due bit hanno lo stesso nome è perché sono in qualche modo correlati.
	Scrivere quindi la descrizione con la inline-label solo nel bit del parametro più significativo,
	lasciando solo un riferimento alla descrizione al posto del bit del parametro meno significativo. 
	Ad esempio:
	il bit f_enable della variabile func_flagv viene abilitato
	solo se il bit f_enable del parametro is0_conf è abilitato
	o se il bit f_enable del parametro is_sw_set è abilitato.
	In questo caso ha più senso	scrivere nella variabile func_flagv le descrizioni con le label,
	inserendo nei parametri is0_conf e is_sw_set dei link alla variabile func_flagv per le descrizioni.
	EVITARE LE DUPLICAZIONI DI CODICE: non scrivere la stessa descrizione in due punti diversi del codice,
	perché altrimenti in futuro si faranno errori.

ATTENZIONE:
	sebbene si sia creato un meccanismo per la verifica automatica della corrispondenza
	tra parametri/variabili nel firmware e quelli sul manuale,ù
	NON è stato possibile creare un equivalente meccanismo di verifica
	per i nomi dei parametri/variabili presenti sugli schemi a blocchi.
	Questo significa che è responsabilità di chi aggiorna il manuale ricordarsi di aggiornare anche gli schemi a blocchi
	in presenza di variazioni di nomi di parametri e variabili.
	Per la stessa ragione, indipendentemente dai nomi delle variabili, se il firmware viene modificato nel suo funzionamento
	non c'è modo di verificarlo se non conoscendo il codice.
	è quindi importante che chi modifica il firmware comunichi le novità sul funzionamento a chi cura il manuale.	

-----------------------
CONVENZIONI DA SEGUIRE:
-----------------------

RIFERIMENTI ipertestuali:
ogni volta che si cita un elemento (parametro, variabile, capitolo, figura) del manuale, creare sempre un link ipertestuale.
Esempio:
	SBAGLIATO:
	Per usare questo blocco, abilitare FunctionGenerator da Task Programmin.
	Questo blocco funziona correttamente soltanto se eseguito con periodo di TsF, è quindi necessario eseguirlo dentro task1.
	CORRETTO: 
	Per usare questo blocco, abilitare :ref:`FunctionGenerator <FunctionGenerator>` da :ref:`CAP_task_programming`.
	Questo blocco funziona correttamente soltanto se eseguito con periodo di :ref:`TsF`, è quindi necessario eseguirlo dentro task1.
	


PARAGRAFI:
	(consigliato) utilizzare l'opzione Word Wrap (a capo automatico)
	(alt+Z in Visual Studio code oppure sotto il menu Visualizza in altri editor di testo)
	scrivere i paragrafi in una sola riga di sorgente (che l'editor visualizza in righe separate)
	andare a capo solo quando si vuole creare un nuovo paragrafo.
	Questo facilita la divisione in paragrafi con gettext per la vesione tradotta.

TABELLE:
	- per tabelle piccole utilizzare il metodo preferito
	  (spesso è più comodo definirla direttamente nel sorgente)
	- per tabelle medio-grandi procedere nel seguente modo:
			1. creare un file separato nome_tabella.csv
			   all'interno della stessa cartella del sorgente
			   dove si vuole che compaia la tabella
			2. modificare il file csv inserendo i dati della tabella
			   (per questo è molto comoda l'estensione Edit csv di VScode)
			3. includere il file csv con la direttiva ..csv-table
	  così è semplice modificare la tabella, basta modificare il file .csv

ORGANIZZAZIONE dei sorgenti (cartella contents dentro source):
(nota: per "parte" s'intende un insieme di capitoli)
(richiamo: dentro source c'è il file index.rst che richiama in ordine tutte le parti)
la cartella "contents" è divisa in sottocartelle,
	ciascuna sottocartella corrisponde a una parte del documento (insieme di capitoli)
	ciascuna sottocartella contiene un file 0_index.rst e altri file .rst (sorgenti dei capitoli)
il file index.rst richiama in ordine gli indici (0_index.rst) di ogni parte
ogni file 0_index.rst richiama in ordine tutti i file .rst dei vari capitoli di quella parte
(nota: il prefisso "0_" serve solo per comodità, così appare come primo file nel file explorer)
(nota: quanto detto vale in modo semplice e lineare per tutti i capitoli, tranne "Parametri e variabili",
quest'ultimo capitolo ha una struttura un po' più complessa perché deve ricalcare l'organizzazione del firmware)

Importante: l'ordine dei capitoli è definito esclusivamente all'interno dei file *index.rst
			di conseguenza:
			- l'ordine con cui si visualizzano file e cartelle all'interno del file explorer non conta
			- se si vuole spostare una parte:
			  	spostare una riga all'interno di index.rst
			- se si vuole spostare un capitolo o un paragrafo:
			  	spostare una riga all'interno del corrispondente file 0_index.rst
			- se si vuole aggiungere un capitolo:
			  	creare un nuovo file .rst e richiamarlo nel corrispondente file 0_index.rst

LABEL:
- usare lettere maiuscole per il prefisso FIG, SEC, CAP, PAR, ...
- usare lettere minuscole per il resto
- usare underscore per separare le parole
Esempi:
	FIG_schema_a_blocchi.svg
	CAP_velocity_loop_parameters
attenzione:
	il sistema di label e riferimenti è case-insensitive,
	quindi le label cap_current, cap_Current e CAP_current vengono interpretate allo stesso modo
attenzione:
	non utilizzare descrizioni senza prefisso a meno che non si tratti di parametri/variabili
Esempio sbagliato:
	task_programming
Esempio corretto:
	CAP_task_programming.
Esempio sbagliato:
	serigrafia_scheda_10_20
Esempio corretto:
	FIG_serigrafia_scheda_10_20.
Questo per evitare che si creino conflitti tra label,
infatti potrebbe esserci una label FIG_scheda_10_20 e una label CAP_scheda_10_20
che senza prefissi andrebbero in conflitto.

TITOLI:
- per i titoli, sopra-e-sotto-lineare con i seguenti simboli:
	# per le parti
	* per i capitoli
	= per le sezioni (oppure sotto-capitoli|***|)
	- per le sottosezioni

  |***| Questa nota vale solo per il capitolo Parametri e variabili
  		per sotto-capitolo s'intende ad esempio basicPar2
	    che è strutturato come capitolo a se stante
		ma fa parte del capitolo Basic Parameters.

FIGURE:
	- salvare tutte le figure nella cartella _static/figure organizzate PER ARGOMENTO in sottocartelle.
		esempio:
			tutte le figure che sono fotografie di parti della scheda 10.20, dentro un'unica cartella,
			indipendentemente dal fatto che quelle figure vengono richiamate in un unico capitolo o in più capitoli.
		eventualmente creare sottocartelle per organizzarle meglio, sempre per argomento.
		esempio:
			una sottocartella "schedine ausiliarie" con dentro le fotografie delle schedine ausiliarie.
		EVITARE la suddivisione delle figure per capitoli.
		Ovviamente per i casi particolari in cui la suddivisione per argomento coincide con quella per capitoli, nessun problema!
		Motivazione: se si organizzano le figure per capitoli succede che:
		- se si decide di cancellare un capitolo o spostare una figura,
		  per ogni figura spostata bisognerà spostare anche la figura nella nuova cartella
		  e modificare tutti i riferimenti a quelle figure all'interno dei sorgenti.
		- si finisce per avere cartelle di capitoli piene di figure di argomento disomogeneo
		- supponiamo di voler aggiornare tutte le immagini di un certo tipo
		  (ad esempio, è cambiata la grafica di FwWriter e si vogliono aggiornare le figure),
		  senza neanche doverle cercare nel manuale,
		  tutte le figure con screenshot di FwWriter dovrebero essere dentro la stessa cartella,
		  quindi basterà cambiare tutte quelle dentro quella cartella.
	- per far riferimento a file di figure all'interno dei sorgenti .rst
		utilizzare sempre percorsi assoluti che cominciano con /_static/...
		NON usare percorsi relativi ad esempio ../../../_static/...
		(il file config.rst imposta sphinx per considerare /_static/ come la root per le figure,
		così facendo il comando per creare la figura funzionerà anche se
		si sposta la il comando su un altro file .rst con profondità diversa.)


SCHEMI A BLOCCHI:
	SOFTWARE: utilizzare libreoffice draw per disegnare le figure
			  con libreoffice si disegna nei file .odg
			  poi si esporta il disegno in formato .svg
	CONVENZIONI:
		- per ogni figura:
			salvare sia il file sorgente (.odg) che il file esportato (.svg)
		  	usando lo stesso nome e salvandoli nella stessa cartella, così compariranno vicini ordinandoli per nome
		  Esempio:
		  	dentro la cartella figure/..., salvare sia schema.odg che schema.svg
		- evitare di esportare più disegni nello stesso file odg
		  (è preferibile tenere in file separati con corrispondenza 1-a-1 con le figure del manuale)
	CREARE nuove figure o schemi con libreoffice:
		creare un nuovo file <nome>.odg con libreoffice
		salvarlo nella cartella dove si vuole conservare la figura
		<nome> deve essere lo stesso nome della figura che si richiamerà nel codice sorgente 
		disegnare cercando di mantenere una coerenza con le altre figure
		(consiglio: partire da una figura esistente e modificarla per mantenere lo stesso stile)
		selezionare la porzione di disegno che si vuole esportare (teoricamente dovrebbe essere tutto, quindi select all)
		FILE->Export
		(la cartella selezionata dovrebbe essere automaticamente la stessa del file .odg, altrimenti cambiarla)
		modificare l'estensione selezionando "SVG" nel menu "Save as type"
		(il nome dovrebbe essere già corretto, altrimenti modificarlo in <nome>.svg)
		selezionare il riquadro "Selection" <-- questo è importante! Altrimenti la figura non viene ritagliata bene.
	MODIFICARE figure esistenti:
		trovare il file .odg con il nome della figura
		modificare la figura
		ricordarsi di salvare il file .odg modificato
		esportare in SVG con lo stesso nome, quindi sovrascrivendo il file obsoleto


EXCEL dei parametri:
se si modifica il file excel, per aggiornare i dati nelle tabelle all'interno del manuale:
- eseguire la macro che rigenera il dizionario python dal file excel
Nota: il nome della variabile all'interno del file rst non verrà cambiato.
se la modifica al file excel comporta anche il nome di un parametro/variabile:
- usare la funzione CRTL+SHIFT+F per sostituire all'interno di tutto il progetto tutti i nome della variabile/parametro con quello nuovo.


PRIMA DELLA PUBBLICAZIONE:
	prima di pubblicare il manuale dopo un aggiornamento,
	controllare tramite il motore di ricerca del html che non siano rimasti "todo"
	perché quando sphinx non trova un parametro o una variabile nel dizionario creato dalla macro di excel
	è programmato per scrivere "todo" al posto della variabile.

	controllare anche che non ci siano errori di compilazione, ad esempio riferimenti a label mancanti.
	controllare che non ci siano warning, ad esempio file che non sono stati inclusi in nessun indice.

	In generale, utilizzare TODO come parola chiave all'interno del manuale per segnare quella parte come "da rivedere"
	in una seconda passata si cercheranno all'interno del manuale tutti i TODO e si procederà a sistemare le parti rimaste in sospeso.
	



COMANDI UTILI SINTASSI rst (reStructuredText):
	per le note a pie pagina...
	per i riferimenti incrociati ...
	per aggiungere un capitolo o paragrafo ...
	per spostare un capitolo o paragrafo ...
	per grassetto, per ...
	--> link a pagine con tutorial

	... vedi documentazione:
		- https://docutils.sourceforge.io/rst.html
		- https://docutils.sourceforge.io/docs/user/rst/quickstart.html
		- https://docutils.sourceforge.io/docs/user/rst/quickref.html
		- https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt
		- https://docutils.sourceforge.io/docs/ref/rst/introduction.html
		- https://sphinx-tutorial.readthedocs.io/step-1/
		- https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html



-----------------------------------------------------
PER GESTIONE DELLA TRADUZIONE (PROGETTO MULTI-LINGUA)
-----------------------------------------------------
riferimenti:
https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#update-your-po-files-by-new-pot-files
https://www.codingwiththomas.com/blog/my-sphinx-best-practice-for-a-multiversion-documentation-in-different-languages
https://sphinx-intl.readthedocs.io/en/master/

Premessa:
	- l'estensione .pot significa "Portable Object Template".
	- l'estensione .po significa "Portable Object"
	I file .pot vengono creati dal file sorgente e contengono un elenco di tutte le stringhe (titoli, didascalie, paragrafi, ...) nella lingua originale
	Da un file .pot si può creare o aggiornare un file .po
	I file .po sono delle mappe che fanno corrispondere ogni stringa del file .pot con la relativa traduzione
	Quindi esisterà sempre un solo file .pot, mentre esisterà un file .po per ogni lingua nella quale si vuole tradurre l'originale
	Se si modifica il sorgente originale bisogna prima ricreare il file .pot
	L'operazione di aggiornamento di un file .po consiste nella fusione delle nuove stringhe presenti nel file .pot aggiornato con quelle presenti nel file .po da aggiornare
	Il file .po aggiornato contiene comunque la traduzione delle vecchie stringhe

VERIFICARE in via preliminare:
	- intallazione pacchetto sphinx Internationalization: $ pip install sphinx-intl
	- presenza delle righe nel file conf.py:
		- locale_dirs = ['locale/']
		- gettext_compact = False

	per approfondimenti sul termine "locale":
		https://en.wikipedia.org/wiki/Internationalization_and_localization
		https://en.wikipedia.org/wiki/Locale_(computer_software)
	per approfondimenti su gettext e i file .po:
		https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html

SELEZIONARE la lingua desiderata come lingua principale
si tratta della lingua con cui sono scritti i sorgenti
ad es. per selezionare l'italiano, nel file conf.py deve essere scritto
	language = 'it'

GENERARE il file .pot (contiene un elenco aggiornato di tutte le stringhe da tradurre)
		dalla cartella di progetto:
				$ sphinx-build -M gettext ./source ./build
		dalla cartella make:
  (alternativa) $ .\update_pot.bat
  (alternativa) $ make gettext

	(il file .pot si troverà dentro la cartella build/gettext)

GENERARE o aggiornare il file .po per le traduzioni nella lingua desiderata
(esempio per la lingua inglese --> en)

		dalla cartella di progetto:
				$ sphinx-intl update -p ./build/gettext -l en
		dalla cartella make:
  (alternativa) $ .\update_po.bat

	così dentro la cartella source/locale/en/LC_MESSAGES si troverà il file .po aggiornato

MODIFICARE il file .po (compito di chi gestisce la traduzione)
	il file .po può essere aperto con un editor compilando gli spazi predefiniti per inserire le traduzioni
	o in alternativa, con un programma apposito (es Poedit) si può aprire il file .po e modificarlo più facilmente
	Poedit permette anche di inserire commenti e segnalare le stringhe che non sono state ancora tradotte o che hanno subito modifiche
	da valutare l'utilizzo di copilot per la compilazione/traduzione automatica del file .po

RICOMPILARE i sorgenti selezionando la lingua desiderata:
	A questo punto, compilando il progetto con make pdf, make html oppure sphinx-autobuild
	si creerà la documentazione nella lingua specificata nel file conf.py
	Quindi basterà cambiare il valore della variabile language dentro conf.py per cambiare la lingua del documento compilato.

ALTRO:
	Ipotizzando di fare una modifica nei file sorgenti nella lingua originale, bisognerà

		1. ricreare il file pot: $ make gettext
		2. aggiornare i file po: $ sphinx-intl update -p build/gettext
		3. modificare i file po con le nuove traduzioni (Poedit aiuta molto)
		4. ricompilare nella lingua desiderata

	Come gestire figure che sono in lingue diverse?

		... ancora non implementato, vedi: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-figure_language_filename


----------------------------------------------
Come gestire le versioni diverse del firmware:
----------------------------------------------

	1. aggiornare un progetto del manuale X fintanto che si aggiorna la versione del firmware X
	2. una volta rilasciata la versione X del firmware, il progetto del manuale X si archivia e non si modifica più
	3. se ne crea una copia, si rinomina in X+1 e si aggiorna di pari passo allo sviluppo della versione del firmware X+1.