0043. Sito di documentazione generato da docs/ con VitePress

• Stato: Accettata
• Data: 2026-09-14
• Decisori: Team BI/ETL

Contesto

La documentazione di noeva-etl è ampia e curata — guida allo sviluppo, panoramica di prodotto, schede di connettori e pipeline, runbook, oltre quaranta ADR — ma esiste solo come markdown nel repository. Si legge bene su GitHub o nell'editor, se sai già dove cercare. Non si legge bene se sei chi usa la piattaforma (un operatore che apre l'app, un referente che deve capire cosa significa una run partial) o chi deve creare un processo con Claude Code senza conoscere il repository: manca un punto d'ingresso per percorsi, manca una ricerca, e i concetti che si capiscono meglio vedendoli — un grafo, il percorso di un record scartato — restano descritti a parole.

Il vincolo è la policy di documentazione (docs/conventions/documentation.md): una fonte di verità e doc disallineata = bug. Un sito che ricopia i contenuti in pagine sue diventerebbe la seconda copia che diverge, cioè proprio il difetto che la policy vieta.

Decisione

Un sito statico generato da docs/ così com'è, con VitePress (dipendenza di sviluppo, insieme a vue, mermaid e gray-matter). I markdown restano la fonte e restano leggibili su GitHub; il sito aggiunge navigazione, ricerca e alcune pagine interattive.

• Sorgente. srcDir è docs/. Sono esclusi i piani storici (docs/plans/), la configurazione per le skill engineering (docs/agents/) e il template dei runbook. La config è in docs/.vitepress/.
• Percorsi. Le pagine nuove stanno in docs/guide/: Usare Noeva ETL (app desktop, esito di una run) e Creare con Claude Code (dal bisogno al processo, compositore del prompt, catalogo degli strumenti), più il grafo interattivo e l'esploratore delle decisioni. Descrivono il percorso e rimandano ai documenti di riferimento, senza ricopiarli.
• Dati letti dai documenti, non ricopiati. I componenti interattivi leggono i contenuti a ogni build tramite data loader: i tipi di nodo dalla tabella in GUIDA_SVILUPPO.md, la mappa Talend dal README.md, gli ADR dai loro file, comandi, subagent e skill dal frontmatter in .claude/. Se un documento cambia forma e il dato non si trova più, la build fallisce con un messaggio che nomina il documento.
• Sidebar generata per le sezioni che crescono da sole (connettori, schede pipeline, runbook, ADR): una scheda nuova compare senza toccare la config.
• Link. I documenti linkano liberamente file fuori da docs/ (../CLAUDE.md, ../../src/…). Un plugin markdown-it li riscrive verso GitHub (branch dev); i link fra pagine pubblicate li gestisce VitePress, che fallisce la build su un link morto.
• Mermaid resta un blocco ```mermaid nei documenti e nel sito diventa un componente che carica la libreria solo nel browser, e solo sulle pagine che la usano.
• Stile allineato a noeva-etl-ui: stessi font self-hostati, stesso marchio (logo NOEVA e wordmark «ETL» in GRUPPO4D), stessi colori per tipo di nodo, tema scuro NDS.
• Gate. pnpm run docs:build entra in pnpm run check e in CI: un link morto o un documento che il sito non sa rendere rompono la PR, come un test rosso.
• Hosting. Rinviato al momento di questa decisione; risolto da ADR-0044: il sito vive nell'app desktop, al posto della guida in-app; la variante pubblica si pubblica anche su Cloudflare Workers (ADR-0045). In locale resta pnpm run docs:dev.

Alternative considerate

• HTML scritto a mano. Massima libertà di design, ma i contenuti sarebbero una seconda copia dei markdown, da tenere allineata a mano. Scartata per la policy di documentazione.
• Astro Starlight. Ottimo generatore, ma si aspetta i contenuti in src/content/docs/ e l'interattività passa da MDX: avrebbe chiesto di spostare o convertire i documenti esistenti.
• Docusaurus. React e MDX: stesso problema di conversione, e un peso maggiore per un sito di un centinaio di pagine.
• MkDocs Material. Maturo, ma porta Python nella toolchain di un progetto solo Node, e l'interattività richiede JavaScript scritto a parte.
• Estendere la pagina /guida dell'app. È in JSX e deve restare autosufficiente (niente renderer markdown nell'app, niente link esterni dalla webview Tauri): non può ospitare la documentazione di riferimento.

Conseguenze

• Positive. Un punto d'ingresso per chi usa e per chi crea, con ricerca locale in italiano; le pagine interattive (grafo, compositore del prompt, catalogo, esploratore degli ADR) restano allineate perché leggono i documenti; la build del sito è un controllo in più di allineamento fra codice e doc.
• Costi. Quattro dipendenze di sviluppo in più (mermaid è la più pesante: si installa anche nello stage di build dell'immagine Docker, che fa pnpm install completo, ma non finisce nell'immagine finale). Circa sei secondi in più sul gate.
• Vincoli per chi scrive i documenti. VitePress compila il markdown come template Vue: un tag HTML sconosciuto fuori da un blocco di codice rompe la build. Il caso più frequente — un segnaposto come <pipeline> finito a inizio riga dopo un a capo — è gestito da docs/.vitepress/lib/placeholder-lines.ts; gli altri li segnala la build.
• Da tenere allineato. La mappa "strumento → attività" del catalogo (docs/.vitepress/lib/claude-assets.ts): uno strumento nuovo compare comunque, ma sotto "Altro" finché non gli si assegna un'attività. La pagina /guida dell'app, che qui restava una sintesi a sé, ora mostra questo stesso sito (ADR-0044).