docs: minor docs updates and apply strict mode in Github (#72)

* feat(docs): create doc for mkdocs, small back improvement, comment on data config.py
* feat: create a mkdocs-requirements.txt file 
* check mkdocs is now in --strict mode

.github/workflows/checks.yml

@@ -222,7 +222,6 @@ jobs:
         with:
           python-version: "3.10"
           cache: "pip"
-      - run: pip install mkdocs mkdocs-material mkdocstrings[python] mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin pymdown-extensions
-
+      - run: pip install -r mkdocs-requirements.txt
       - name: Run documentation validation
-        run: mkdocs build
+        run: mkdocs build --strict

back/README.md

@@ -5,19 +5,19 @@
 Le backend d'IArbre calcule l'occupation des sols et les différents indices (plantabilité, etc.).
 Le backend utilise [Django](https://www.djangoproject.com/) et une base de données [PostGIS](https://postgis.net/).
 
-Avec Django, nous avons créer différents **aplications**.
-`iarbre_data` correspond au calcul de l'occupation des sols.
-Vous pouvez ensuite utiliser les autres applications telles que `plantability` pour calculer les indices (plantabilité, etc).
+Il existe trois applications Django :
 
-Ce backend a été développé suite à l'[implémentation V1](https://forge.grandlyon.com/erasme/script-recalcul-calque) par [Exo-dev](https://exo-dev.fr/).
+- `iarbre_data` pour les calculs d’occupation des sols ;
+- `plantability` pour le calcul de l'indice de plantabilité. Le développement correspond à une réplication de [l'implémentation V1](https://forge.grandlyon.com/erasme/script-recalcul-calque) réalisée par [Exo-dev](https://exo-dev.fr/).
+- `api` pour rendre accessible ces résultats par à une API rest ;
 
 ## Contenu
 
-- [Données requises](#données-requises)
-- [Déploiement avec Ansible](#déploiement-avec-ansible)
+- [Données requises](#donnees-requises)
+- [Déploiement avec Ansible](#deploiement-avec-ansible)
 - [Installation manuelle](#installation-manuelle)
-- [Génération de la base de données](#génération-de-la-base-de-données)
-- [Démarrage du backend](#démarrage-du-service-backend)
+- [Génération de la base de données](#generation-de-la-base-de-donnees)
+- [Démarrage du backend](#demarrage-du-service-backend)
 - [Aide](#aide)
 
 ## Données requises

back/iarbre_data/data_config.py

@@ -384,6 +384,10 @@
     },
 ]
 
+# Plantability factor.
+# The higher, the more plantable it is
+# For example, it's easier to plant a tree on wasteland
+# than at an airport
 FACTORS = {
     "Souches ou emplacements libres": 3,
     "Arbres": 1,

back/iarbre_data/management/commands/c02_init_grid.py

@@ -24,7 +24,13 @@
 
 
 def create_tiles_for_city(
-    city, grid_size, tile_shape_cls, logger, batch_size=int(1e6), unit=None, a=1
+    city,
+    grid_size,
+    tile_shape_cls,
+    logger,
+    batch_size=int(1e6),
+    unit=None,
+    a=1,
 ) -> None:
     """
     Create tiles (square or hexagonal) for a specific city.
@@ -242,9 +248,6 @@ def _create_grid_city(
             unit (float): The size of the hexagon in meters (for hexagonal grid only).
             a (float): The ratio of the hexagon (for hexagonal grid only).
             grid_size (float): The size of the grid in meters (for square grid).
-
-        Returns:
-            None
         """
         print(f"Selected city: {city.name} with id {city.id}.")
         # Get already existing tiles

back/iarbre_data/management/commands/c04_compute_factors.py

@@ -15,7 +15,7 @@
 TILE_BATCH_SIZE = 10_000
 
 
-def has_intersection(geom, tiles_index):
+def has_intersection(geom, tiles_index) -> bool:
     """
     Check if a geometry intersects with any tile.
 
@@ -24,7 +24,7 @@ def has_intersection(geom, tiles_index):
         tiles_index (geopandas.GeoDataFrame.sindex):  R-tree spatial index of the tiles.
 
     Returns:
-        bool: True if the geometry intersects with any tile, False otherwise.
+        True if the geometry intersects with any tile, False otherwise.
     """
     if geom is None or geom.is_empty:
         return False
@@ -43,7 +43,7 @@ def _compute_for_factor_partial_tiles(factor_df, tiles_df, std_area):
         std_area (float): Standard tile area in square meters (m²).
 
     Returns:
-        list[TileFactor]: List of TileFactor objects to be created in the database
+        (list[TileFactor]): List of TileFactor objects to be created in the database
     """
     # Filter polygons in the bounding box of the tiles
     tiles_index = tiles_df.sindex

deploy/README.md

@@ -1,12 +1,12 @@
-# Mise en production et maintenance avec Ansible d'un site avec Stack Django Vue
+# Scripts de mise en production et maintenance avec Ansible d'un site
 
 ## Stack technique
 
 Principaux outils open-sources
 
 - frontend:
   - Serveur nginx
-  - framework Nuxt 3
+  - framework Vue 3
 - backend: framework Django, gunicorn pour le wsgi
 
 Outils externes potentiellement payants
@@ -17,7 +17,7 @@ Outils externes potentiellement payants
 
 Ce considère donc :
 
-- Que vous utilisez `Nuxt` ou un autre projet qui se compile avec
+- Que vous utilisez Vite ou un autre projet qui se compile avec
   `yarn generate/build` pour le frontend. Adapter
   `roles/frontend/tasks/main.yml:Build frontend code` si nécessaire.
   Il est possible d'utiliser les modes statiques et SSR de Nuxt, en fonction

deploy/roles/docs/tasks/main.yml

@@ -28,13 +28,7 @@
 
 - name: Install MkDocs and dependencies
   pip:
-    name:
-      - mkdocs
-      - mkdocs-material
-      - mkdocstrings[python]
-      - mkdocs-git-revision-date-localized-plugin
-      - mkdocs-minify-plugin
-      - pymdown-extensions
+    requirements: mkdocs-requirements.txt
     virtualenv: "{{ venv.path }}"
 
 - name: Init documentation

docs/docs.md

@@ -0,0 +1,23 @@
+# Documentation
+
+La documentation du projet est construite avec [Mkdocs 📚](https://www.mkdocs.org/).
+
+## Développement & modifications
+
+Pour pouvoir lancer `Mkdocs` en local, vous avez besoin d’installer plusieurs dépendances Python :
+
+```
+pip install -r mkdocs-requirements.txt
+```
+
+Vous pouvez ensuite lancer la documentation en local avec la commande suivante :
+
+```
+mkdocs serve -a localhost:8001
+```
+
+Le port `8000` par défaut de mkdocs étant utilisé par le back de IA·rbre, vous risqueriez un conflit.
+
+!!! warning "Plusieurs fichiers Markdown sont des liens symboliques"
+
+    Afin d'éviter de dupliquer du texte, de nombreux fichiers markdown présents dans le dossier `docs` sont en réalité des liens symboliques vers des fichiers `README.md`. C'est par exemple le cas de `docs/backend/index.md` qui est un lien symbolique vers `back/README.md`.

mkdocs-requirements.txt

@@ -0,0 +1,6 @@
+mkdocs
+mkdocs-git-revision-date-localized-plugin
+mkdocs-material
+mkdocs-minify-plugin
+mkdocstrings[python]
+pymdown-extensions

mkdocs.yml

@@ -55,7 +55,8 @@ nav:
           - Compute Indices: api/c05_compute_indice.md
           - Utils: api/utils.md
   - Frontend: front.md
-  - Deploy: deploy.md
+  - Déploiement: deploy.md
+  - Documentation: docs.md
 
 theme:
   name: "material"