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:

   .. code-block:: bash

      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:

   .. code-block:: bash

      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):

.. code-block:: bash

   # 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.