Merge branch 'main' into production

.github/workflows/Check_lint.yml

@@ -1,33 +1,20 @@
-name: Check lint
+name: Run linters
 
 on:
   pull_request:
     branches:
-      - master
+      - production
       - main
   push:
     branches:
-      - master
+      - production
       - main
 
 jobs:
-  black:
-    name: Check black has been run
+  linter:
+    name: run pre-commit
     runs-on: ubuntu-latest
     steps:
-      - name: Setup git
-        uses: actions/checkout@v3
-
-      - name: Setup python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.9
-
-      - name: Install python dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r web/requirements.app.txt
-          pip install -r web/requirements.dev.txt
-
-      - name: Check black has nothing to do
-        run: black . --check
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+      - uses: pre-commit/[email protected]

.github/workflows/Check_local_run.yml

@@ -3,11 +3,11 @@ name: Check local run
 on:
   pull_request:
     branches:
-      - master
+      - production
       - main
   push:
     branches:
-      - master
+      - production
       - main
 
 jobs:
@@ -24,22 +24,30 @@ jobs:
   test-local:
     name: Run test locally
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python:
+          - '3.11'
+          - '3.10'
+          - '3.9'
+          - '3.8'
+
     steps:
       - name: Setup git
         uses: actions/checkout@v3
 
       - name: Setup python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: ${{ matrix.python }}
 
       - name: Install python dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r web/requirements.app.txt
           pip install -r web/requirements.dev.txt
       - name: Check local environment tests
-        run: pytest --envfile web.env.example
+        run: pytest
 
   healthy-containers:
     name: Check containers run

.github/workflows/Documentation.yml

@@ -0,0 +1,37 @@
+---
+name: Documentation
+on:
+  push:
+    branches:
+      - production
+      - main
+  pull_request:
+    branches:
+      - production
+      - main
+jobs:
+  tests:
+    name: ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - uses: actions/cache@v1
+        with:
+          path: ~/.cache/pip
+          key: pip|${{ hashFiles('web/requirements.doc.txt') }}
+
+      - name: Install python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r web/requirements.doc.txt
+
+      - name: Run unit tests
+        run: sphinx-build documentation build/sphinx/html

.github/workflows/Test_coverage.yml

@@ -3,11 +3,11 @@ name: Check coverage
 on:
   pull_request:
     branches:
-      - master
+      - production
       - main
   push:
     branches:
-      - master
+      - production
       - main
 
 jobs:
@@ -18,41 +18,25 @@ jobs:
       - name: Setup git
         uses: actions/checkout@v3
 
-      - name: Setup python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.9
-
-      - name: Switch to main branch
+      - name: Get the git branch
         uses: actions/checkout@v3
         with:
-          ref: ${{ github.event.repository.default_branch }}
+          ref: main # TODO: dynamically get the branch against which the PR will be merged?
 
-      - name: Install previous python dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r web/requirements.app.txt
-          pip install -r web/requirements.dev.txt
-
-      - name: Get previous coverage
-        id: get_coverage
-        run: |
-          coverage run -m pytest --envfile web.env.example
-          coverage json
-          export PERCENT_COVERED=$(python -c "import json;print(json.load(open('coverage.json'))['totals']['percent_covered'])")
-          echo "percent_covered=$PERCENT_COVERED" >> $GITHUB_OUTPUT
-
-      - name: Switch to branch to merge
-        uses: actions/checkout@v3
+      - name: Setup python
+        uses: actions/setup-python@v4
         with:
-          fetch-depth: 0
-          ref: ${{ github.event.pull_request.head.sha }}
+          python-version: 3.11
 
-      - name: Install new python dependencies
+      - name: Install python dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r web/requirements.app.txt
           pip install -r web/requirements.dev.txt
+          pip install diff-cover
+
+      - name: Run unit tests with coverage
+        run: pytest --cov --cov-report=xml
 
-      - name: Check that coverage at least equals to main coverage
-        run: pytest --envfile web.env.example --cov --cov-fail-under=${{ steps.get_coverage.outputs.percent_covered }}
+      - name: Check that the edited lines are all covered
+        run: diff-cover coverage.xml --fail-under=100

.pre-commit-config.yaml

@@ -1,30 +1,32 @@
 ---
 repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.3.4'
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: fix-byte-order-marker
       - id: trailing-whitespace
         exclude: "\\.svg$|\\.map$|\\.min\\.css$|\\.min\\.js$|\\.po$|\\.pot$"
       - id: end-of-file-fixer
         exclude: "\\.svg$|\\.map$|\\.min\\.css$|\\.min\\.js$|\\.po$|\\.pot$"
       - id: check-toml
-  - repo: https://github.com/asottile/reorder_python_imports
-    rev: v3.10.0
+  - repo: https://github.com/pycqa/isort
+    rev: "5.13.2"
     hooks:
-      - id: reorder-python-imports
-        args: ["--application-directories", "canaille"]
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.0.284'
+      - id: isort
+        name: isort (python)
+        args: ["--force-single-line-imports", "--line-length", "120"]
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.5
     hooks:
-      - id: ruff
-        args: [--fix, --exit-non-zero-on-fix]
+      - id: docformatter
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.10.1
+    rev: v3.15.2
     hooks:
       - id: pyupgrade
         args: ["--py38-plus"]
-  - repo: https://github.com/psf/black
-    rev: 23.7.0
-    hooks:
-    - id: black

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: documentation/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: web/requirements.doc.txt

CONTRIBUTING.md

@@ -4,32 +4,6 @@ Bienvenue sur B3Desk, et merci de prendre le temps de vous intéresser à la con
 
 Vous trouverez ici les quelques indications qui permettront à B3Desk de grandir et de se développer que nous avons jugées intéressantes. N'hésitez pas à faire des suggestions !
 
-**Sommaire**
-
-[Lancer B3Desk localement](#lancer-b3desk-localement)
-
-- [Docker](#Docker)
-- [Environnement de développement](#environnement-de-développement)
-    - [Installation locale](#installation-locale)
-    - [Poetry](#Poetry)
-
-[Soumettre des modifications](#soumettre-des-modifications)
-
-- [Prérequis](#Prérequis)
-    - [Validité du code](#validité-du-code)
-    - [Conventions de code](#conventions-de-code)
-    - [Intégration continue GitHub](#intégration-continue-github)
-- [Pull requests](#pull-requests)
-    - [Workflow](#Workflow)
-    - [Commits](#Commits)
-- [Cas particuliers](#cas-particuliers)
-    - [Migration des données](#migration-des-données)
-    - [Traductions](#Traductions)
-
-[Mise en forme des pages](#mise-en-forme-des-pages)
-
-[Liens utiles](#liens-utiles)
-
 ## Lancer B3Desk localement
 
 ### Docker
@@ -43,7 +17,7 @@ Pour lancer l'application et coller au plus proche des conditions de production,
 - broker : le broker redis qui maintient une liste de tâches dans laquelle vient se servir le worker
 - tokenmock : un mock qui vient reproduire les conditions de prod de distribution d'un token pour la communication entre B3Desk et l'instance Nextcloud de l'utilisateur
 
-Vous trouverez plus d'informations concernant la persistance des données pour certains de ces conteneurs dans la documentation [./documentation/dockerPersistence.md](./documentation/dockerPersistence.md).
+Vous trouverez plus d'informations concernant la persistance des données pour certains de ces conteneurs dans {doc}`la documentation <dockerPersistence>`.
 
 1. Configurer l'application web en créant le fichier `web.env` à partir du fichier `web.env.example`. Ce nouveau fichier est précisé dans `docker-compose.override.yml` qui vient surcharger le fichier `docker-compose.yml` lorsqu'aucun fichier n'est précisé dans la commande `docker compose`.
 Pour que les liens vers le service BBB fonctionne, il est nécessaire de configurer les variables d'environnement BIGBLUEBUTTON_ENDPOINT et BIGBLUEBUTTON_SECRET.
@@ -114,6 +88,11 @@ ou bien dans l'environnement Poetry avec pytest (dont certains settings sont dan
 pytest
 ```
 
+Pour tester le code sur les différentes versions de python en cours, et prévenir des incompatibilités avec des versions futures, utilisez :
+```bash
+tox
+```
+
 #### Conventions de code
 
 Le code python doit suivre les conventions de la PEP 8. Dans les dépendance de développement du projet, on retrouve `flake8` et `black`.
@@ -137,7 +116,7 @@ Ainsi, lorsque vous ferez un commit, black sera automatiquement lancé et format
 
 GitHub Actions est utilisé afin de s'assurer que le code reste propre et fonctionnel et que les conteneurs peuvent communiquer entre eux pour s'assurer que l'embarquement de nouveaux développeur·euses sur de nouvelles machines est possible.
 
-Cette intégration continue fait tourner des conteneurs Docker, les [fichiers de requirements](#poetry) doivent donc être maintenus à jour.
+Cette intégration continue fait tourner des conteneurs Docker, les fichiers de requirements doivent donc être maintenus à jour.
 
 La CI GitHub est utilisée pour :
 - lancer les tests dans un environnement local (sans conteneur docker) : pour permettre aux développeurs d'être indépendant de docker sur leurs machines
@@ -156,7 +135,7 @@ Le projet est organisé de la façon suivante :
 
 - Les modification sont faites sur une `branche` de votre **fork**.
 - Lorsque le développement est prêt, une *pull request* vers la branche `main` du projet d'*origine* est réalisée
-- Une fois ce [développement validé](./documentation/pullRequestValidation.md), les mainteneurs du projet vont *merger* ces modifications sur `main`
+- Une fois ce {doc}`développement validé <../maintainers/pullRequestValidation>`, les mainteneurs du projet vont *merger* ces modifications sur `main`
 - Lorsque suffisamment de modifications sont faites dans `main`, les mainteneurs peuvent décider de créer une nouvelle version du projet
 - La branche `main` est *mergée* dans la branche `production`, référente pour les déploiements du projet B3Desk
 
@@ -187,15 +166,13 @@ En production, les migrations sont réalisées automatiquement par `run_webserve
 
 #### Traductions
 
-Vous trouverez toutes les informations sur la traduction dans cette [documentation](./documentation/translation.md).
+Vous trouverez toutes les informations sur la traduction dans cette {doc}`documentation <translation>`.
 
 ## Mise en forme des pages
 
-Le service utilise le style du Système de Design de l'État (dsfr) :
-
-https://gouvfr.atlassian.net/wiki/spaces/DB/overview?homepageId=145359476
+Le service utilise le style du [Système de Design de l'État (dsfr)](https://gouvfr.atlassian.net/wiki/spaces/DB/overview?homepageId=145359476)
 
 ## Liens utiles
 
-- https://docs.bigbluebutton.org/dev/api.html
-- https://mconf.github.io/api-mate/
+- [docs.bigbluebutton.org/dev/api.html](https://docs.bigbluebutton.org/dev/api.html)
+- [mconf.github.io/api-mate](https://mconf.github.io/api-mate/)

Makefile

@@ -4,17 +4,23 @@
 
 install-dev:
 	# Install dependencies for local development usage
-	poetry env use 3.8 ; poetry install --with dev ; poetry shell
+	poetry install --with dev --with doc; poetry shell
 	pre-commit install
 
+export-dependencies: export-base-dependencies export-dev-dependencies export-doc-dependencies
+
 export-base-dependencies:
 	# Update requirements file for web service
-	poetry export --without-hashes --with task-management -o web/requirements.app.txt
+	poetry export --without-hashes -o web/requirements.app.txt
 
 export-dev-dependencies:
 	# Update requirements file for development environment used in GitHub Actions
 	poetry export --without-hashes --only dev -o web/requirements.dev.txt
 
+export-doc-dependencies:
+	# Update requirements file for development environment used in GitHub Actions
+	poetry export --without-hashes --with doc -o web/requirements.doc.txt
+
 translation-extract:
 	# Extract messages to be translated with:
 	pybabel extract --mapping-file web/translations/babel.cfg --output-file web/translations/messages.pot --keywords lazy_gettext web
@@ -26,3 +32,6 @@ translation-update:
 translation-compile:
 	# Compile translation catalogs with:
 	pybabel compile --directory web/translations
+
+doc:
+	sphinx-build documentation build/sphinx/html