Skip to main content

Strategia di Integrazione Documentale Moduli Esterni

Questo documento descrive l'architettura scelta per aggregare la documentazione tecnica che risiede in repository Git separati all'interno del portale centrale WEP Digital Hub.

Obiettivo​

Aggregare documentazione specifica (es. ETL Budget, Backend Specs) mantenendo la Single Source of Truth nei repo di origine, garantendo al contempo un'esperienza utente pulita (non mescolare documenti tecnici verticali con l'architettura generale).

1. Architettura UX: "The Island Pattern"​

Per evitare il sovraccarico di informazioni, adottiamo un pattern a "isola":

  • Sidebar Isolate: Ogni modulo esterno ha la propria sidebar. Quando l'utente naviga la documentazione di "Budget Contracts", vede solo quel sommario.
  • Navbar Centralizzata: La navigazione tra i moduli avviene tramite la Navbar principale (es. menu a tendina "Progetti" o "Servizi").

2. Implementazione Tecnica: Docusaurus Multi-Instance​

Utilizziamo il plugin @docusaurus/plugin-content-docs in modalità multi-istanza. Ogni istanza punta a una cartella locale.

Configurazione Esempio (In progress):​

plugins: [
  [
    '@docusaurus/plugin-content-docs',
    {
      id: 'budget-contracts',
      path: process.env.BUDGET_DOCS_PATH || '../../wep_budgetcontracts/docs',
      routeBasePath: 'modules/budget-contracts',
      sidebarPath: require.resolve('./sidebarsBudget.js'),
    },
  ],
]

3. Requisiti per la CI/CD (Chiara)​

Il portale viene generato come sito statico. Affinché il build abbia successo, la pipeline deve preparare il file system.

Step suggeriti nella GitHub Action:​

  1. Checkout Portale: Clone di wep-digital-hub.
  2. Checkout Moduli Esterni:
    • Clone di wep_budgetcontracts in ../wep_budgetcontracts.
    • Clone di wep-backend-docs in ../wep-backend-docs.
  3. Build: Esecuzione di npm run build nel portale.

[!IMPORTANT] I path devono essere coerenti tra ambiente locale e CI. L'uso di variabili d'ambiente (es. BUDGET_DOCS_PATH) rende il sistema flessibile a diverse strutture di folder.

4. Manutenzione​

  • Single Source of Truth: Qualsiasi modifica ai documenti viene fatta nel repository del modulo.
  • Aggiornamento Portale: Il portale si aggiorna automaticamente ad ogni build clonando l'ultima versione dei moduli (es. branch main).