Vai al contenuto

Gestione del Portale di Documentazione

Obiettivo

Questa guida descrive come avviare, aggiornare, compilare e pubblicare il portale di documentazione tecnica basato su MkDocs Material utilizzato per il nostro progetto.

Il portale si trova nella root della repository ed è organizzato come segue:

  • mkdocs.yml: file di configurazione principale (tema, menu, estensioni, Mermaid);
  • docs/: cartella contenente i documenti sorgente in formato Markdown;
  • site/: cartella di output HTML generata dal comando mkdocs build;
  • requirements.txt: dipendenze Python per la build automatica su piattaforme hosting (Cloudflare Pages, CI/CD).

Struttura delle sezioni

docs/
├── index.md                 # Panoramica generale e stack tecnologico
├── setup/                   # Setup locale, portale doc e variabili d'ambiente
├── architecture/            # Architettura, flussi principali e modello dati
├── traceability/            # Matrice di tracciabilità dei requisiti (RF1 - RF95)
└── handover/                # Debito tecnico noto, TODO e raccomandazioni

Installazione locale

Prerequisiti

È necessario un ambiente Python (consigliato Python 3.8 o superiore) con pip installato.

Creazione dell'ambiente virtuale e dipendenze

Dalla cartella principale del repository:

python -m venv .venv
.\.venv\Scripts\pip.exe install -r requirements.txt

(Se su Windows si usa il launcher py: py -3.8 -m venv .venv)

Script pronti all'uso (Windows)

Nella cartella Scripts/Docs/ sono inclusi gli script batch per velocizzare i comandi più frequenti:

  • Scripts/Docs/InstallDocs.bat: crea il virtual environment e installa le dipendenze;
  • Scripts/Docs/ServeDocs.bat: avvia il server locale con hot-reload;
  • Scripts/Docs/BuildDocs.bat: compila la documentazione statica in site/.

Come avviare la documentazione

Server di sviluppo con hot-reload (consigliato)

.\.venv\Scripts\mkdocs.exe serve -a 127.0.0.1:8000

Oppure avviando Scripts\Docs\ServeDocs.bat.

Il portale sarà accessibile all'indirizzo:

  • http://127.0.0.1:8000/

Ogni modifica salvata nei file .md o in mkdocs.yml aggiornerà automaticamente la pagina nel browser.

Compilazione statica

Per generare il bundle statico:

.\.venv\Scripts\mkdocs.exe build

I file HTML/CSS/JS finali saranno generati nella directory site/.

Hosting su Cloudflare Pages

Metodo 1: Collegamento automatico Git (Consigliato)

  1. Nel pannello di Cloudflare: Workers & Pages → Create application → Pages → Connect to Git.
  2. Seleziona il repository e il branch (es. docs).
  3. Imposta i seguenti parametri di build:
  4. Framework preset: None
  5. Build command: pip install -r requirements.txt && mkdocs build
  6. Build output directory: site
  7. Environment variables: aggiungi PYTHON_VERSION = 3.10

Cloudflare compilerà e pubblicherà automaticamente il sito a ogni commit.

Metodo 2: Caricamento manuale (Direct Upload)

  1. Esegui la build locale con Scripts\Docs\BuildDocs.bat o mkdocs build.
  2. Nel pannello Cloudflare Pages: seleziona Direct Upload.
  3. Trascina direttamente la cartella site/ nel browser.

Oppure tramite CLI Wrangler: 

npx wrangler pages deploy site --project-name=hapgree-docs

Come aggiungere o modificare pagine

1. Modifica o creazione file Markdown

I nuovi contenuti vanno aggiunti all'interno della cartella docs/ nella sottocartella appropriata:

  • Nuove guide di setup -> docs/setup/
  • Nuovi approfondimenti architetturali -> docs/architecture/
  • Aggiornamenti su debito o refactoring -> docs/handover/

2. Aggiornamento del menu di navigazione

Ogni nuova pagina deve essere registrata nella sezione nav di mkdocs.yml per comparire nella barra di navigazione laterale:

nav:
  - Configurazione:
      - Ambiente Locale: setup/local-environment.md
      - Variabili d'Ambiente: setup/env-variables.md
      - Gestione della Documentazione: setup/documentation-portal.md

3. Diagrammi Mermaid

Il supporto a Mermaid è già configurato in mkdocs.yml. È possibile inserire diagrammi direttamente nei blocchi di codice con il tag mermaid:

flowchart TD
    A[Richiesta Client] --> B[API Controller]
    B --> C[Service Backend]

Linee guida per la documentazione

  • Mantenere la coerenza con i nomi reali di classi, ViewModel, DTO e servizi presenti nel codice.
  • Distinguere chiaramente le responsabilità del client mobile da quelle gestite dai servizi di backend.
  • Verificare periodicamente la matrice di tracciabilità (docs/traceability/matrix.md) ad ogni modifica rilevante dei requisiti o dei moduli.