From 8e5f8684f78ce51a3349386d16b4b1a048aec407 Mon Sep 17 00:00:00 2001
From: viennet <emmanuel.viennet@gmail.com>
Date: Mon, 22 Jul 2024 16:40:22 +0300
Subject: [PATCH] MAJ conventions codage

---
 docs/DevConventions.md | 73 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 67 insertions(+), 6 deletions(-)

diff --git a/docs/DevConventions.md b/docs/DevConventions.md
index e12f2030c..1fa9b3f0e 100644
--- a/docs/DevConventions.md
+++ b/docs/DevConventions.md
@@ -16,20 +16,22 @@ Pour les nouveaux codes, respecter les principes suivants:
   conduit à dupliquer du code (qui existe en général dans le serveur) et
   augmente les coûts de maintenance.
 
-## Formatage du code
+## Conventions de codage
+
+### Formatage du code
 
 - l'usage de **[black](https://black.readthedocs.io/en/stable/)** est obligatoire
 - l'usage de pylint et mypy est fortement recommandé
 - Pour le code JS, indentation avec 2 espaces (sous VS Code, utiliser *Prettier*).
 
-## Conventions standard Python
+### Conventions standard Python
 
 On se tient à la PEP8, c'est à dire en résumé:
 `UneClasse`, `une_fonction`, `_une_fonction_privee`, `une_variable`, `UNE_CONSTANTE_GLOBALE`.
 
 Les noms de fichiers sont en minuscules sans accents ni espaces, `comme_ceci.py`.
 
-## Annotations de type
+### Annotations de type (typehints)
 
 On annote les paramètres et résultats des fonctions.
 
@@ -40,9 +42,9 @@ def _upload_justificatif_files(
     ...
 ```
 
-## Vues et templates
+## Pages et templates
 
-Les vues utilisent un template *Jinja*, fichier avec extension j2.
+Les vues utilisent un template *Jinja2*, fichier avec extension j2.
 
 On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template.
 
@@ -53,10 +55,69 @@ def un_exemple(...):
     return render_template(".../un_exemple.j2")
 ```
 
+Le template aura typiquement avec la structure suivante:
+
+```jinja
+{% extends "sco_page.j2" %}
+
+{% block app_content %}
+    <h1>Titre</h1>
+{% endblock app_content %}
+```
+
+Pour les pages dans un semestre (avec barre menu etc.), on utilisera `<h2>` au
+lieu de `<h1>`.
+
+### Templates habituels
+
+Les templates suivants sont les plus utilisés pour les pages:
+
+- `base.j2` pages hors département (accueil, configuration, ...)
+
+- `sco_page.j2` page standard dans un formsemestre: avec sidebar et barre de
+  menu du semestre.
+
+- `sco_dept_page.j2` page dans un département (avec sidebar) mais sans formsemestre (pas de
+  barre de menu)
+
+### Constantes définies dans les templates ScoDoc
+
+Le `context_processor` `inject_sco_utils()` ajoute des objets pour accès à tous
+les templates ScoDoc:
+
+- `scu` : le module `sco_utils.py` (diverses fonctions utilitaires et variables
+  de config.)
+- `sco` : des données sur le contexte, notamment les préférences, le
+  formsemestre et l'étudiant courants (resp. `sco.formsemestre` et `sco.etud`)
+
+### Appel d'un template page
+
+Pour mémoire, l'appel d'un template dans une vue se fait ainsi:
+
+```py
+render_template( "votre_template.j2",
+      title="Changer de référentiel de compétences",
+      autre_variable=...
+  )
+```
+
+
+### Classes css
+
+`scodoc.css` (et à partir de 9.7, `scodoc97.css`) définissent quelques classes à usage général:
+
+- `div.scobox`: boite (bords arrondis, fond uni) regroupant des éléments.
+
+  - `div.scobox-title` le titre de la boite
+  - `div.scobox-buttons` boutons en bas de boite.
+
+- `p.help`, `div.help`: explications, aide.
+- ...
+
 ## Accès à la base de donnée
 
 Sauf exception (requêtes exotiques, problèmes de performance) à discuter, les
-accès à la base se font à travers l'ORM *SQLAlchemy*. Mes modèles sont définis
+accès à la base se font à travers l'ORM *SQLAlchemy*. Les modèles sont définis
 dans `app/models`, sauf les comptes utilisateurs qui sont dans
 `/app/auth/models.py`.