feat: add local technical docs.

.github/workflows/node.js.yml

@@ -34,6 +34,13 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
+    - uses: actions-rs/toolchain@v1
+      with:
+        toolchain: stable
+
+    - name: Install mdbook
+      run: (test -x $HOME/.cargo/bin/mdbook || cargo install mdbook)
+
     - name: Cache node_modules
       id: cache-node_modules
       uses: actions/cache@v4

.gitignore

@@ -11,6 +11,7 @@ elm-stuff
 /public/icomoon/demo.html
 /public/main.css
 /public/main.css.map
+/public/tech-docs
 /server-app.js
 /src/Static/Json.elm
 /xls

README.md

@@ -8,34 +8,41 @@ L'application est accessible [à cette adresse](https://ecobalyse.beta.gouv.fr/)
 
 ## Socle technique et prérequis
 
-Le frontend de cette application est écrite en [Elm](https://elm-lang.org/). Vous devez disposer d'un environnement [NodeJS](https://nodejs.org/fr/) 14+ et `npm`. Pour le backend vous devez disposer d'un environnement [python](https://www.python.org/) >=3.11, [pipenv](https://pipenv.pypa.io/) et [gettext](https://www.gnu.org/software/gettext/) sur votre machine.
+Le frontend de cette application est écrite en [Elm](https://elm-lang.org/). Vous devez disposer d'un environnement [NodeJS](https://nodejs.org/fr/) 14+ et `npm`. Pour le backend vous devez disposer d'un environnement [python](https://www.python.org/) >=3.11, [pipenv](https://pipenv.pypa.io/) et [gettext](https://www.gnu.org/software/gettext/) sur votre machine. Le paquet [mdbook](https://rust-lang.github.io/mdBook/) est également requis pour générer la documentation technique du projet.
 
-## Installation
+## Installation de l'environnement de développement
 
-### Frontend
-
-    $ npm install
+```shell
+$ npm install
+$ pipenv install
+```
 
-### Backend
+Pour installer `mdbook`, si vous disposez d'un environnement de dévelopement rust:
 
-    $ pipenv install
+```shell
+$ test -x $HOME/.cargo/bin/mdbook || cargo install mdbook
+```
 
 Assurez-vous d'avoir un PostgreSQL >=16 qui tourne localement si vous souhaitez vous rapprocher de l'environnement de production. À défaut, `sqlite` sera utilisé.
 
 Pour créer et lancer un PostgreSQL sur le port 5433 en local en utilisant `docker` :
 
-    # Création du volume pour persister les données
-    docker volume create ecobalyse_postgres_data
+```shell
+# Création du volume pour persister les données
+$ docker volume create ecobalyse_postgres_data
 
-    # Lancement du docker postgres 16
-    docker run --name ecobalyse-postgres -e POSTGRES_PASSWORD=password -d -p 5433:5432 -v ecobalyse_postgres_data:/var/lib/postgresql/data postgres:16
+# Lancement du docker postgres 16
+$ docker run --name ecobalyse-postgres -e POSTGRES_PASSWORD=password -d -p 5433:5432 -v ecobalyse_postgres_data:/var/lib/postgresql/data postgres:16
 
-    # Création de la base de données ecobalyse_dev
-    docker exec -it ecobalyse-postgres createdb -U postgres ecobalyse_dev
+# Création de la base de données ecobalyse_dev
+$ docker exec -it ecobalyse-postgres createdb -U postgres ecobalyse_dev
+```
 
 Vous devriez pouvoir y accéder via votre `psql` local avec la commande suivante :
 
-    psql -U postgres -p 5433 -h localhost ecobalyse_dev
+```shell
+$ psql -U postgres -p 5433 -h localhost ecobalyse_dev
+```
 
 ## Configuration
 
@@ -60,21 +67,27 @@ En développement, copiez le fichier `.env.sample`, renommez-le `.env`, et mette
 
 Pour utiliser le PostgreSQL lancé avec docker, configurez la variable `SCALINGO_POSTGRESQL_URL` comme ceci :
 
-    SCALINGO_POSTGRESQL_URL=postgres://postgres:password@localhost:5433/ecobalyse_dev
+```shell
+$ SCALINGO_POSTGRESQL_URL=postgres://postgres:password@localhost:5433/ecobalyse_dev
+```
 
 ## Chargement des données par défaut
 
 Pour initialiser la base de données (attention, toutes les données présentes, si il y en a, seront supprimées) :
 
-    $ pipenv run ./backend/update.sh
+```shell
+$ pipenv run ./backend/update.sh
+```
 
 ## Développement
 
 ### Environnement de développement local
 
 Le serveur local de développement se lance au moyen des deux commandes suivantes :
 
-    $ npm start
+```shell
+$ npm start
+```
 
 Trois instances de développement sont alors accessibles :
 
@@ -93,27 +106,37 @@ Le build sur le CI échouera si les fichiers python, javascript et json ne sont
 
 Pour installer les hooks pre-commit, exécutez la commande suivante :
 
-    $ pipenv run pre-commit install
+```shell
+$ pipenv run pre-commit install
+```
 
 Un hook de pre-commit sera alors configuré pour vérifier que le code est bien formaté avant de permettre le commit. Le hook corrigera les erreurs dans la mesure du possible. Il vous suffira alors d'ajouter les modifications à votre staging, git puis à refaire votre commit.
 
 Il est possible de lancer la vérification du formatage à la main grâce à la commande suivante :
 
-    $ npm run lint:all
+```shell
+$ npm run lint:all
+```
 
 Si vous voulez lancer la correction automatique de tous les problèmes détectés, lancez :
 
-    $ npm run fix:all
+```shell
+$ npm run fix:all
+```
 
 Si vous ne souhaitez pas que la vérification se fasse de manière automatique, vous pouvez désinstaller pre-commit et les hooks associés :
 
-    $ pipenv run pre-commit uninstall
+```shell
+$ pipenv run pre-commit uninstall
+```
 
 ## Compilation
 
 Pour compiler la partie client de l'application :
 
-    $ npm run build
+```shell
+$ npm run build
+```
 
 Les fichiers sont alors générés dans le répertoire `build` à la racine du projet, qui peut être servi de façon statique.
 
@@ -127,7 +150,9 @@ Chaque _Pull Request_ effectuée sur le dépôt est également automatiquement d
 
 Pour ajouter une variable d'environnement sur une application, il est recommandé d'utiliser le CLI scalingo qui permet d'ajouter des valeurs qui contiennent plusieurs lignes (à la différence de l'interface graphique qui ne le permet pas) :
 
-    scalingo --app ecobalyse env-set "MY_VAR=$(cat fichier.key)"
+```shell
+$ scalingo --app ecobalyse env-set "MY_VAR=$(cat fichier.key)"
+```
 
 ### Lien avec ecobalyse_private
 
@@ -147,7 +172,7 @@ Les variables d'environnement doivent être positionnées via l'interface de [co
 
 Pour lancer le serveur applicatif complet (frontend + backend), par exemple depuis un environnement de production, la démarche est la suivante :
 
-```
+```shell
 $ npm run build
 $ npm run server:start
 ```
@@ -166,7 +191,9 @@ en détaille l'installation et l'utilisation.
 
 Le versioning de l'application permet de revenir à des anciennes versions d'Ecobalyse. Pour que ce versioning puisse fonctionner, les anciennes versions (<= 2.0.0) doivent être patchées rétroactivement. Le script `./bin/build-specific-app-version.sh` permet de générer une version spécifique de l'application et d'appliquer les patchs si nécessaire. Par exemple, pour générer la version `1.3.2` (le deuxième paramètre est le commit du répertoire data associé) :
 
-    pipenv run ./bin/build-specific-app-version.sh v1.3.2 3531c73f23a1eb6f1fc6b9c256a5344742230fcf
+```shell
+pipenv run ./bin/build-specific-app-version.sh v1.3.2 3531c73f23a1eb6f1fc6b9c256a5344742230fcf
+```
 
 Un fichier `v1.3.2-dist.tar.gz` sera disponible à la racine du projet et un répertoire `v1.3.2` aura été créé dans `versions/`.
 

package.json

@@ -14,8 +14,9 @@
   ],
   "scripts": {
     "build": "npm run server:build && rimraf dist && npm run build:init && parcel build index.html --public-url ./",
-    "build:init": "./bin/update-version.sh && mkdir -p dist && cp -r public/* dist/ && npm run db:build",
+    "build:init": "./bin/update-version.sh && npm run build:tech-docs && mkdir -p dist && cp -r public/* dist/ && npm run db:build",
     "build:standalone-app": "npm run build && npm run server:build && cp server-app.js dist/ && cp openapi.yaml dist/",
+    "build:tech-docs": "mdbook build tech-docs -d ../public/tech-docs && mdbook test tech-docs",
     "processes:build": "elm make src/ComputeAggregated.elm --output=compute-aggregated-app.js && node compute-aggregated.js",
     "decrypt": "./bin/decrypt",
     "encrypt": "./bin/encrypt",

server.js

@@ -87,6 +87,7 @@ app.use(
 
 app.use(
   express.static("dist", {
+    index: "index.html",
     setHeaders: (res) => {
       // Note: helmet sets this header to `0` by default and doesn't allow overriding
       // this value

tech-docs/.gitignore

@@ -0,0 +1 @@
+book

tech-docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Nicolas Perriault"]
+language = "fr"
+multilingual = false
+src = "src"
+title = "Ecobalyse - Documentation technique"

tech-docs/src/README.md

@@ -0,0 +1 @@
+../../README.md

tech-docs/src/SUMMARY.md

@@ -0,0 +1,4 @@
+# Summary
+
+- [README](./README.md)
+- [Gestion des tests](./gestion-des-tests.md)

tech-docs/src/gestion-des-tests.md

@@ -0,0 +1,22 @@
+> 💡 **Prérequis**
+>
+> Pour exécuter et régler les problèmes de tests en échec suite à la mise à jour d’impacts, il convient de disposer d’une installation locale du projet. Les instructions d’installation et de configuration sont décrites [dans le README sur le dépôt.](https://github.com/MTES-MCT/ecobalyse/blob/master/README.md)
+
+**Si suite à une mise à jour des impacts ou des coefficients de complément les tests échouent, voici la méthode pour régler la situation :**
+
+- Depuis votre branche à jour en local et depuis un terminal, lancez `npm test`
+- Vérifiez dans les rapports de tests si les échecs ou différences relevés sont attendus ou non
+- Si les échecs **ne sont pas attendus**, réglez le problème et soumettez les modifications sur la branche afin que les tests passent à nouveau
+- Si les échecs **sont attendus** — par exemple lorsque vous mettez à jour des impacts ou des compléments — et que vous vous souhaitez mettre à jour les tests afin de prendre en compte les nouvelles valeurs obtenues :
+    - Pour les tests unitaires, mettez à jour les valeurs en échecs directement dans les tests Elm (`tests/**/*Test.elm`)
+    - Pour les tests e2e (serveur), il faudra copier le ou les fichiers suivants, générés automatiquement à chaque lancement de la suite de tests via `npm test`:
+        - Pour le textile : `cp tests/e2e-textile-output.json tests/e2e-textile.json`
+        - Pour l’alimentaire : `cp tests/e2e-food-output.json tests/e2e-food.json`
+    - Une fois que les tests passent tous à nouveau, vous pouvez commiter et pousser les changements sur votre branche distante, le build de votre pull-request devrait revenir au vert et être déployé automatiquement en recette.💡C’est toujours une bonne idée d’aller sur la recette Web vérifier que tout fonctionne comme prévu.
+
+
+> 💡 **Cas particulier de la détection d’évolutions inhabituelles d’impacts**
+>
+> Si vous obtenez des échecs sur les tests de type `Food ingredients ecoscore deviation`, il vous faut également vérifier si ces écarts sont attendus ou non.
+>
+> S’ils sont attendus, il vous faut commenter le test en question, merger votre branche dans master, puis pousser un commit sur master qui décommente le test à nouveau afin que le contrôle puisse être effectué sur les branches et pull-requests créées par la suite.