Contribuire al progetto

Grazie per il tuo interesse a contribuire al Trentino Living Atlas (TLA)! Questa pagina spiega come preparare l’ambiente, le linee guida per le modifiche e come aggiornare la documentazione.

Obiettivi dei contributi

  • Migliorare qualità e copertura della documentazione

  • Risolvere bug e migliorare la stabilità

  • Introdurre piccole funzionalità ben motivate e testate

  • Mantenere coerenza stilistica (codice e docs)

Prerequisiti

  • Python 3.11 (consigliato; RTD usa 3.11)

  • Pip/venv

  • Git

  • Accesso in lettura al repository

Setup ambiente di sviluppo

  1. Clona il repository e crea un virtualenv:

    git clone <repo-url> tla
cd tla
python3 -m venv .venv
. .venv/bin/activate
pip install -U pip

  2. Installa le dipendenze principali (vedi la documentazione del progetto). Per la sola documentazione, puoi installare i requisiti minimi:

    pip install -r requirements/docs-rtd.txt

  3. Variabili d’ambiente utili per lo sviluppo:

    • DJANGO_SETTINGS_MODULE=webgis.settings.dev per esecuzione locale completa

    • Per la sola build docs su RTD non è necessario, RTD usa impostazioni dedicate.

Linee guida per le modifiche al codice

  • Mantieni le modifiche atomicamente piccole e con un messaggio commit chiaro.

  • Segui lo stile del progetto e le convenzioni Django/Wagtail.

  • Aggiungi note di migrazione quando necessario (modelli o dipendenze).

  • Evita dipendenze non necessarie e riduci gli import pesanti in fase di import modulo.

Linee guida per la documentazione

  • Formato: reStructuredText (RST) con Sphinx.

  • Ogni pagina deve avere un titolo con sottolineatura coerente.

  • Se aggiungi una nuova pagina, includila nella toctree in docs/index.rst.

  • Usa esempi minimi e riproducibili; mantieni i blocchi di codice marcati con il lexer corretto (es. bash, python, rst).

  • Evita riferimenti diretti a risorse locali; preferisci link relativi o note esplicative.

Costruire la documentazione in locale

Build completa (con autodoc disabilitato su RTD ma attivabile in locale):

# Opzione 1: solo documentazione (senza app caricate)
make -C docs html

# Opzione 2: generare autodoc completa in locale
export DJANGO_SETTINGS_MODULE=webgis.settings.dev
make -C docs html

Note su Read the Docs (RTD)

  • La configurazione di RTD è fornita in .readthedocs.yaml.

  • RTD usa un ambiente Python 3.11 e costruisce con Sphinx usando docs/conf.py.

  • Per evitare errori di import in RTD, l’autodoc di API e modelli è disabilitata sui server RTD; le relative direttive sono mostrate come esempio nelle pagine api.rst e database.rst.

  • Per vedere l’autodoc completo, effettua la build in locale con le app e il database configurati.

Inviare una Pull Request

  1. Crea un branch descrittivo (es. docs/fix-toctree-contributing).

  2. Effettua le modifiche e verifica localmente: - make -C docs html e controlla che non compaiano errori.

  3. Apri una PR spiegando: - Cosa cambia e perché - Impatti sulla documentazione o su RTD - Eventuali passi di migrazione o configurazione

  4. Attendi il code review; potrebbero essere richieste piccole modifiche.

Suggerimenti utili

  • Se vedi avvisi tipo “document isn’t included in any toctree”, ricordati di aggiungere la pagina in docs/index.rst.

  • Se vedi errori autodoc: failed to import module, esegui la build con un DJANGO_SETTINGS_MODULE valido oppure rimuovi/commuta temporaneamente le direttive autodoc nella pagina interessata.

Contatti

Per domande, apri una issue sul repository o proponi direttamente una PR minima con la modifica suggerita.