Vai al contenuto

Contribuire alla Documentazione

Guida per contribuire alla documentazione tecnica del progetto SGV GE.CO.

Prerequisiti

  • Python 3.8+ (consigliato 3.11)
  • pip (package manager Python)
  • Git (per il plugin git-revision-date)

Setup Locale

1. Installare le dipendenze

Dalla root del progetto:

pip install -r requirements-docs.txt

Questo installa:

  • mkdocs - Generatore sito statico
  • mkdocs-material - Tema Material Design
  • pymdown-extensions - Estensioni Markdown avanzate
  • mkdocs-git-revision-date-localized-plugin - Date revisione da Git

2. Avviare il server di preview

mkdocs serve

Il sito sara disponibile su http://localhost:8000 con live reload automatico: ogni modifica ai file .md aggiorna la pagina in tempo reale.

3. Build statico (verifica)

mkdocs build --strict

Il flag --strict trasforma i warning in errori. Usalo per verificare che non ci siano link rotti o problemi prima di committare.

Struttura Directory

docs/
├── index.md                    # Home page
├── architecture/               # Architettura sistema
│   ├── overview.md
│   ├── modules.md
│   ├── data-model.md
│   └── security-model.md
├── api/                        # Documentazione API
│   ├── rest-api.md
│   └── openapi/
├── integrations/               # Integrazioni PA
│   ├── pa-services.md
│   ├── anpr.md, pnd.md, inad.md, pagopa.md, mctc.md
├── development/                # Guide sviluppo
│   ├── setup.md
│   ├── build-and-deploy.md
│   ├── coding-standards.md
│   ├── testing-guide.md
│   └── contributing-docs.md    # ← Questa guida
├── operations/                 # Operazioni e runbook
│   ├── deployment-guide.md
│   ├── monitoring.md
│   ├── backup-restore.md
│   └── runbooks/
├── database/                   # Database
│   ├── schema.md
│   ├── migrations/
│   └── performance-tuning.md
├── security/                   # Sicurezza
│   ├── threat-model.md
│   ├── authentication.md
│   ├── data-protection.md
│   └── audit-logging.md
└── adr/                        # Architecture Decision Records
    ├── index.md
    └── template.md

La navigazione e definita in mkdocs.yml nella sezione nav:.

Come Scrivere Documentazione

Convenzioni generali

  • Lingua: Italiano per contenuti descrittivi, inglese per termini tecnici e codice
  • File naming: kebab-case.md (es: build-and-deploy.md)
  • Titolo: Ogni file inizia con un heading # Titolo di livello 1
  • Lunghezza: Preferire pagine focalizzate su un singolo argomento

Estensioni Markdown disponibili

Admonitions (avvisi)

!!! note "Titolo opzionale"
    Contenuto della nota.

!!! warning
    Contenuto del warning.

!!! danger "Attenzione"
    Operazione pericolosa.

!!! tip
    Suggerimento utile.

!!! info
    Informazione aggiuntiva.

Tipi disponibili: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote.

Blocchi codice con syntax highlighting

```java title="VvVerbale.java" linenums="1"
@Entity
@Table(name = "vv_verbale")
public class VvVerbale {
    @Id
    private Long id;
}
```

Linguaggi supportati: java, sql, bash, xml, yaml, json, python, javascript, e molti altri.

Tab sincronizzati

=== "Maven"

    ```bash
    mvn clean install
    ```

=== "Gradle"

    ```bash
    gradle build
    ```

Diagrammi Mermaid

```mermaid
graph LR
    A[MLib] --> B[GeCo.Alfa]
    A --> C[GecoService]
    A --> D[ElaborazioneService]
```

Tasklist

- [x] Task completato
- [ ] Task da fare

Abbreviazioni e definizioni

Il sistema usa JPA per la persistenza.

*[JPA]: Java Persistence API

Riferimenti interni

Per linkare altre pagine della documentazione:

Vedi la [guida al setup](setup.md) per i dettagli.
Consulta la sezione [architettura](../architecture/overview.md).

Usa path relativi al file corrente.

Workflow Contribuzione

1. Crea un branch

git checkout ExtraCDS_FermiSequestri
git pull origin ExtraCDS_FermiSequestri
git checkout -b docs/descrizione-modifica

2. Modifica la documentazione

Edita o crea i file .md nella cartella docs/. Se aggiungi un nuovo file, registralo nella sezione nav: di mkdocs.yml.

3. Verifica in locale

# Preview con live reload
mkdocs serve

# Build di verifica (controlla errori)
mkdocs build --strict

4. Commit e push

git add docs/ mkdocs.yml
git commit -m "docs: Descrizione della modifica"
git push origin docs/descrizione-modifica

Convenzione commit

Usa il prefisso docs: per i commit di documentazione.

5. Crea Merge Request

Crea una MR su GitLab verso ExtraCDS_FermiSequestri con label documentation.

Pubblicazione

La documentazione viene pubblicata automaticamente su doc.verbalia.cloud dopo il merge su ExtraCDS_FermiSequestri.

La pipeline CI/CD:

  1. docs:build - Builda il sito con mkdocs build --strict
  2. docs:deploy-staging - Copia i file statici sul server via rsync

Il sito e servito da un container Nginx dietro Traefik con certificato HTTPS Let's Encrypt.

Aggiungere una Nuova Sezione

  1. Crea il file .md nella cartella appropriata sotto docs/
  2. Aggiungi la voce nella sezione nav: di mkdocs.yml
  3. Verifica con mkdocs serve che la navigazione sia corretta
  4. Se necessario, crea una sottocartella con un index.md

Riferimenti