2  Struttura del repositorio

Data di Pubblicazione

7 ottobre 2026

Questo capitolo vuole essere una breve guida alla struttura del repositorio ed alle funzionalità che esso offre.

2.1 Descrizione dei file

Da un punto di vista del documento propriamente detto, i file principali sono:

  • _quarto.yml: contiene la struttura di alto livello del documento, inclusi i metadati rilevanti, le impostazioni di quarto, e l’indice dei file;
  • index.qmd: è il sorgente per la prima pagina del documento—quella a cui punta il link all’html statico;
  • meta.yml: è un file ausiliario che contiene la versione corrente del documento e la data di rilascio associata.
  • references.bib: è il file di bibliografia, che nella versione iniziale contiene una sola entry di esempio.

Ci sono poi alcuni file ancillari:

  • README.md: è il README di più alto livello del repositorio—quello che appare nella pagina principale del repositorio su Codeberg;
  • LICENSE: è banalmente il file della licenza, che dovrebbe essere coerente con la sezione corrispondente del libro;

Ultimo, ma non per importanza, il flusso di lavoro:

  • Makefile: contiene i comandi della shell per le operazioni principali—anteprima, compilazione e rilascio.

2.1.1 Testo e figure

La struttura del repositorio è pensata in modo che i capitoli, e eventualmente le appendici, siano file .qmd separati nella cartella chapters, mentre le figure siano fisicamente nella cartella figures.

La versione iniziale del repositorio ha una manciata di figure nella sotto-cartella figures/static con l’idea che eventuali figure generate programmaticamente potrebbero essere collocate in una nuova cartella figures/generated, mentre gli script per generarle potrebbero andare in figures/scripts.

Ovviamente questa struttura di base può essere modificata a piacimento.

2.2 Controllo delle versioni

Per comodità il numero di versione a la data di pubblicazione sono contenute nel file separato meta.yml.

Questo file può essere editato manualmente per tracciare la versione del documento ad ogni rilascio.

Per chi usasse versioning semantico, il piccolo script python tools/release.py permette di automatizzare il controllo della versione. Più precisamente

[lbaldini@pcpi0188 quarto_guide]$ python tools/release.py --help
usage: release.py [-h] {major,minor,micro}

Release a new version of the package.

positional arguments:
  {major,minor,micro}  The version bump mode.

options:
  -h, --help           show this help message and exit

In pratica lo script è pensato per automatizzare le seguenti operazioni:

  • incrementare il numero di versione;
  • aggiornare il file meta.yml;
  • aggiungere una riga con il numero di versione all’inizio del file history.qmd;
  • fare il commit ed il push dei nuovi file nel repositorio;
  • fare un tag del repositorio stesso con la versione corrente.