Merge branch 'master' of https://scodoc.org/git/viennet/DocScoDoc

Reviewed-on: viennet/DocScoDoc#14

docs/BUT.md

@@ -43,7 +43,7 @@ niveaux) et UEs.
 
 ## Calcul des notes
 
-Les rôles des SAÉ et ressources étant symétriques, on appellera dans al suite (et
+Les rôles des SAÉ et ressources étant symétriques, on appellera dans la suite (et
 dans ScoDoc) *module* un objet de type SAÉ _ou_ ressource.
 
 Dans la suite, on considère les poids et coefficients toujours positifs ou
@@ -80,7 +80,7 @@ réduit d'apprentissages critiques:
 
 La note (moyenne) d'un module (SAÉ ou ressource) se calcule à partir de ses
 évaluations. Chaque évaluation est pondérée, par un poids $p$ est fixé par
-l'enseignant. ce poids joue le même rôle que le coefficient d'une évaluation
+l'enseignant. Ce poids joue le même rôle que le coefficient d'une évaluation
 classique, mais peut se décliner en plusieurs valeurs, une par UE associée au
 module. 
 
@@ -96,7 +96,7 @@ une UE $u$ *doit* être non nulle; si ce n'est pas le cas, le module sera décla
 
 
 ### Moyenne de module (SAÉ ou ressource)
-La moyenne d'un module est un vecteur, car on a une note moyenne par UE:
+La moyenne d'un étudiant dans un module est un vecteur, car on a une note moyenne par UE:
 
 $$\mu_{m, u} = \frac{\sum_e p_{e,u} \, n_e}{\sum_{e} \, p_{u,e}}$$
 
@@ -110,7 +110,7 @@ $$\mu_m = \frac{\sum_e (\sum_u p_{e,u}) \, n_e}{\sum_{u,e} \, p_{u,e}}$$
 
 On va considérer les coefficients de modules et d'évaluations:
 
-$$\mu_u = \frac{1}{\sum_m c_{u,m}} \, \sum_{m \in u} c_{u,m} \, \frac{\sum_e p_{e,u} \, n_e}{\sum_{e} \, p_{u,e}}$$
+$$\mu_u = \frac{1}{\sum_m c_{u,m}} \, \sum_{m \in u} c_{u,m} \, \frac{\sum_e p_{e,u} \, n_e}{\sum_{e} \, p_{e,u}}$$
 
 L'exemple suivant illustre ce mode de calcul:
 

docs/GuideAdminSys.md

@@ -34,7 +34,7 @@ référer à [GuideInstallDebianDix](GuideInstallDebianDix.md) ou
 ##  Utilisation avancée
 
  * [Interfaçage avec Apogée](ScoDocApogee.md)
- * [API](ScoDocAPI.md) : API JSON ou XML pour interfaçage avec d'autres applications
+ * [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications
  * [ServicesXml](ServicesXml.md) : web services XML pour interfaçage avec d'autres applications (obsolète).
  * [AdminUsers](AdminUsers.md) : gestion des utilisateurs
  * [InterrogationPortail](InterrogationPortail.md) : liaison avec portail

docs/GuideConfig.md

@@ -88,6 +88,20 @@ Exemple: création d'une rôle "Observateur" ayant juste la persmision de "voir"
 
 Ajoute ou retire une permission.
 
+## Ajout/retrait d'un rôle à un utilisateur
+
+    flask user-role username [-d departement] [-a RoleAAjouter] [-r RoleARetirer]
+
+Exemple:
+
+    flask user-role dupont -d MMI -a Observateur
+
+donne le rôle `Observateur` (qui doit déjà exister) à l'utilisateur `dupont` dans
+le département `MMI`.
+
+Si le département n'est pas spécifié, le rôle est donné dans *tous* les
+départements (utile pour certains compte administrateurs ou utilisés en lecture
+par des clients de l'API).
 
 ## Migration des données de ScoDoc 7
 Les données dans ScoDoc 9 ayant un format et une organisation très différents
@@ -118,26 +132,44 @@ Exemple:
 ## Liste des commandes Flask/ScoDoc
 ```
 Commands:
-  clear-cache           Clear ScoDoc cache (currently Redis)
-  create-dept           Create new departement
-  delete-dept           Delete existing departement
-  edit-role             Add [-a] and/or remove [-r] a permission to/from a role
-  import-scodoc7-dept   Import département ScoDoc 7
-  import-scodoc7-users  Import users defined in ScoDoc7 postgresql
-  sco-db-init           Initialize the database.
-  user-create           Create a new user
-  user-db-clear         Erase all users and roles from the database !
-  user-password         Set (or change) user's password
+  clear-cache                    Clear ScoDoc cache This cache (currently...
+  create-dept                    Create new departement
+  create-role                    Create a new role
+  delete-role                    Delete a role       
+  delete-dept                    Delete existing departement
+  dumphelp
+  edit-role                      Add [-a] and/or remove [-r] a permission...
+  import-scodoc7-dept            Import département ScoDoc 7: dept:...
+  import-scodoc7-users           Import users defined in ScoDoc7...
+  list-depts                     If dept exists, print it, else nothing.
+  localize-logo                  Make local to a dept a global logo (both...
+  migrate-scodoc7-dept-archives  Post-migration: renomme les archives en...
+  migrate-scodoc7-dept-logos     Post-migration: renomme les logos en...
+  photos-import-files
+  profile                        Start the application under the code...
+  sco-db-init                    Initialize the database.
+  scodoc-database                print the database connexion string
+  user-create                    Create a new user
+  user-db-clear                  Erase all users and roles from the...
+  user-password                  Set (or change) user's password
+  user-role                      Add or remove a role to the given user...
 
 Usage: app sco-db-init [OPTIONS]
 
   Initialize the database. Starts from an existing database and create all the
   necessary SQL tables and functions.
 
+Options:
+  --erase / --no-erase
+  --help                Show this message and exit.
+
 Usage: app user-db-clear [OPTIONS]
 
   Erase all users and roles from the database !
 
+Options:
+  --help  Show this message and exit.
+
 Usage: app user-create [OPTIONS] USERNAME ROLE DEPT
 
   Create a new user
@@ -145,7 +177,7 @@ Usage: app user-create [OPTIONS] USERNAME ROLE DEPT
 Options:
   -n, --nom TEXT
   -p, --prenom TEXT
-
+  --help             Show this message and exit.
 
 Usage: app user-password [OPTIONS] USERNAME
 
@@ -153,7 +185,14 @@ Usage: app user-password [OPTIONS] USERNAME
 
 Options:
   --password TEXT
+  --help           Show this message and exit.
 
+Usage: app create-role [OPTIONS] ROLENAME [PERMISSIONS]...
+
+  Create a new role
+
+Options:
+  --help  Show this message and exit.
 
 Usage: app edit-role [OPTIONS] ROLENAME
 
@@ -166,42 +205,117 @@ Usage: app edit-role [OPTIONS] ROLENAME
 Options:
   -a, --add TEXT
   -r, --remove TEXT
+  --help             Show this message and exit.
 
+Usage: app user-role [OPTIONS] USERNAME
 
-Usage: app delete-dept DEPT
+  Add or remove a role to the given user in the given dept
+
+Options:
+  -d, --dept TEXT
+  -a, --add TEXT
+  -r, --remove TEXT
+  --help             Show this message and exit.
+
+Usage: app delete-dept [OPTIONS] DEPT
 
   Delete existing departement
 
+Options:
+  --help  Show this message and exit.
 
-Usage: app create-dept DEPT
+Usage: app create-dept [OPTIONS] DEPT
 
   Create new departement
 
+Options:
+  --help  Show this message and exit.
 
-Usage: app import-scodoc7-users 
+Usage: app list-depts [OPTIONS] [DEPTS]...
 
-  Import used defined in ScoDoc7 postgresql database into ScoDoc 9 The old
+  If dept exists, print it, else nothing. Called without arguments, list all
+  depts along with their ids.
+
+Options:
+  --help  Show this message and exit.
+
+Usage: app scodoc-database [OPTIONS]
+
+  print the database connexion string
+
+Options:
+  -n, --name  show database name instead of connexion string (required for
+              dropdb/createdb commands)
+  --help      Show this message and exit.
+
+Usage: app import-scodoc7-users [OPTIONS]
+
+  Import users defined in ScoDoc7 postgresql database into ScoDoc 9 The old
   database SCOUSERS  must be alive and readable by the current user. This
   script is typically run as unix user "scodoc". The original SCOUSERS
   database is left unmodified.
 
+Options:
+  --help  Show this message and exit.
 
-Usage: app import-scodoc7-dept  DEPT DEPT_DB_NAME
+Usage: app import-scodoc7-dept [OPTIONS] DEPT DEPT_DB_NAME
 
   Import département ScoDoc 7: dept: InfoComm, dept_db_name: SCOINFOCOMM
 
+Options:
+  --help  Show this message and exit.
 
-Usage: app clear-cache
+Usage: app migrate-scodoc7-dept-archives [OPTIONS] [DEPT]
+
+  Post-migration: renomme les archives en fonction des id de ScoDoc 9
+
+Options:
+  --help  Show this message and exit.
+
+Usage: app migrate-scodoc7-dept-logos [OPTIONS] [DEPT]
+
+  Post-migration: renomme les logos en fonction des id / dept de ScoDoc 9
+
+Options:
+  --help  Show this message and exit.
+
+Usage: app localize-logo [OPTIONS] LOGO DEPT
+
+  Make local to a dept a global logo  (both logo and dept names are mandatory)
+
+Options:
+  --help  Show this message and exit.
+
+Usage: app photos-import-files [OPTIONS] FORMSEMESTRE_ID XLSFILE ZIPFILE
+
+Options:
+  --help  Show this message and exit.
+
+Usage: app clear-cache [OPTIONS]
 
   Clear ScoDoc cache This cache (currently Redis) is persistent between
   invocation and it may be necessary to clear it during development or tests.
 
 Options:
   --help  Show this message and exit.
+
+Usage: app dumphelp [OPTIONS]
+
+Options:
+  --help  Show this message and exit.
+
+Usage: app profile [OPTIONS]
+
+  Start the application under the code profiler.
+
+Options:
+  -h, --host TEXT     The interface to bind to.
+  -p, --port INTEGER  The port to bind to.
+  --length INTEGER    Number of functions to include in the profiler report.
+  --profile-dir TEXT  Directory where profiler data files are saved.
+  --help              Show this message and exit.
 ```
 
-
-
 ##  Changement des logos apparaissant sur les documents 
 
 *Note: après migration, vos logos de ScoDoc 7 sont installés dans ScoDoc 9*.

docs/GuideDeveloppeurs.md

@@ -9,7 +9,7 @@ Informations pour les développeurs souhaitant étendre ou modifier ScoDoc.
    un serveur Discord ouvert sur invitation aux développeur actifs. Contacter Emmanuel.
  * [Générer de nouveaux formats de bulletins PDF](ApiGenerationBulletinsPdf.md)
  * [Créer de nouveaux types de "parcours"](ApiCreationParcours.md)
- * [API](ScoDocAPI.md) : API JSON ou XML pour interfaçage avec d'autres applications
+ * [API](ScoDoc9API.md) : API JSON ou XML pour interfaçage avec d'autres applications
  * Notes diverses
     * [Discussions pour la future gestion des absences](IdeesGestionAbsences.md)
     * [Anciennes discussions sur la gestion des plannings](IdeesGestionPlannings.md)
@@ -56,7 +56,7 @@ Exemple:
 
 ### Git
 
-Le dépot est <https://scodoc.org/git/viennet/ScoDoc>
+Le dépôt est <https://scodoc.org/git/viennet/ScoDoc>
 
 La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne
 (jusqu'à septembre 2021) version en production.
@@ -86,8 +86,9 @@ basique:
 
 Vous travaillez dans votre branche `ma_branche`. Pour lui appliquer les mises à
 jour de `master` (remote):
-
+```bash
     git pull origin master
+```
 
 #### Commandes utiles, en vrac
 
@@ -97,29 +98,275 @@ jour de `master` (remote):
 #### Refactoring
 
 Lint tous les fichiers modifiés:
-    
+```bash 
     git status | grep modified | grep .py | awk '{print $2}' | xargs pylint -E
-
+```
 Restore les modes au besoin (SAMBA les changent parfois):    
-    
+```bash    
     git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply
-
+```
 Affiche les variables non définies dans un fichier:
-
+```bash
    pylint --disable=all  -e E sco_parcours_dut.py | grep undefined-variable | awk '{print $4;}' | sort | uniq | tr -d \' 
-
+```
 Prépare un sed pour renommer les variables non définies:
-
+```bash
    for f in *.py
    do
    pylint --disable=all  -e E "$f" | grep undefined-variable | awk '{print "sed -i .bak s/"$4"/scu."$4"/ '$f'";}' | sort | uniq | tr -d \'
    done
+```
 
 Note pour travailler sur VirtualBox:
 
     addgroup scodoc vboxsf
 
-### Tests
+### Préparation d'une PR (Pull Request)
+
+#### Principes généraux
+
+Les remarques de cette section visent à obtenir une relecture facile de votre
+demande d'ajout (*pull request*, dite "PR"):
+
+* Éviter les modifications de forme qui ne changent pas le sens du code. L'utilisation de
+  [`black`](https://black.readthedocs.io/) est obligatoire : elle permet de normaliser la présentation
+  du code. cela évite de générer des différences ne représentant que des
+  changements de mise en forme (indentation, passages à la ligne). Cela évite
+  aussi au développeur d'avoir à y réfléchir, autant de temps gagné !
+
+* Avoir un nombre d'étapes de validation faible (idéalement un seul commit pour
+  les PR courantes - peu volumineuses).
+
+* La PR doit toujours être énoncée par rapport au dernier commit de la branche
+  que vous visez (en général `master` du dépôt original).
+
+#### Manipulations
+
+Les manipulations sont décrites selon quatre phases du développement : l'installation,
+la mise en place, le suivi et la livraison.
+
+##### l'installation
+Il est pratique d'avoir en ligne les deux dépôts git distants que vous pouvez
+utiliser : votre dépôt personnel (`https://scodoc.org/git/<user>/<dépôt>.git`) et
+le dépôt officiel (`https://scodoc.org/git/ScoDoc/ScoDoc.git`).
+
+pour ajouter une référence (et lui donner un nom) vers un dépôt distant, entrez
+la commande:
+
+```bash
+  git remote add nom_remote https://scodoc.org/git/ScoDoc/<dépôt>.git
+``` 
+
+Par la suite vous aurez donc une référence vers votre dépôt personnel (`perso`)
+et une référence vers le dépôt officiel (`officiel`). Si vous avez initialement
+cloné l'un des deux dépôts, la référence vers le dépot d'origine existe et a pour nom
+`origin`.
+
+La commande vous exposant tous les dépôts connus est :
+```bash
+  git remote -v
+```
+
+#### Mise en place
+
+L'objectif de ce paragraphe est de créer une branche locale basée sur le master
+du dépôt officiel et bien sur de lui donner un nom.
+
+pour cela (**attention cela va écraser les éventuels fichiers modifiés**. Si vous souhaitez conserver les 
+modifications en cours, encadrez les lignes suivantes par `git stash` (avant) et `git stash apply` (après) :
+
+```bash
+  git reset --hard officiel/master
+  git checkout -b ma_modif 
+```
+À partir de là, vous pouvez modifier, tester, développer et commit votre travail.
+
+#### Suivi
+
+Si votre développement prend plusieurs jours, il est probable que la branche
+principale évolue pendant ce temps.
+
+Pour garder la cohérence, il est nécessaire de réintégrer en local les
+modifications de la branche principale. Ceci peut se faire de deux façons.
+
+ - Une fusion (`merge`) applique toutes les modifications en un seul commit).
+   C'est la méthode couramment utilisée.
+
+ - Un `rebase` rejoue tous les commits de la nouvelle branche par dessus l'état
+   le plus à jour de la branche principale (il en résulte un historique plus
+   linéaire).
+
+Les commandes git correspondantes :
+
+```bash
+  git fetch officiel
+  git merge officiel/master
+```
+ou
+```bash
+  git fetch officiel
+  git rebase officiel/merge
+```
+
+#### La livraison
+
+Ça y est. Vous avez terminé le développement. IL n'y a plus qu'à demander
+l'intégration. Ceci se fait en plusieurs étapes (vous êtes bien sûr toujours sur
+la branche locale `ma_modif` et toutes vos modifications ont été commitées).
+
+##### Étape 1 : faire l'inventaire des fichiers impliqués
+
+```bash
+  git fetch officiel/master
+  git diff --name-only officiel/master
+```
+
+##### Étape 2 : passer black sur les fichiers modifiés
+
+Cette étape est automatique avec les bons réglages sous VSCode (pas trouvé
+l'équivalent sous *pyCharm*).
+
+À défaut les lignes suivantes réalisent le même travail :
+
+```bash
+  for fn in $(git diff --name-only officiel/master)
+  do
+    python3 -m black $fn
+  done 
+```
+
+Faire une première lecture rapide pour vérifier qu'il ne reste pas de fichiers
+modifiés accidentellement.
+
+Pour obtenir la modification sur un fichier spécifique (`app/fichier.py` par exemple)
+```bash
+  git diff officiel/master app/fichier.py
+```
+
+Utilisateurs Windows : Vérifiez bien que les réglages de fin de ligne suivent
+bien les règles Linux (pas de retour chariot (noté CR ou `\r`) en fin de ligne mais un seul caractère line feed 
+(noté LF  ou `\n`). 
+Le cas échéant, réglez votre IDE pour cela.
+
+À ce niveau là de la procèdure, vous n'avez plus dans votre branche locale que les différences strictement
+nécessaires à votre correctif.
+
+##### Étape 3 : résumez tous les commits depuis le point de divergence en un seul commit
+
+Repérez le point de divergence de votre branche locale avec officiel/master
+(normalement `git merge-base HEAD officiel/master`)
+
+Demander un `rebase` interactif depuis ce point :
+
+```bash
+  git rebase -i $(git merge-base HEAD officiel/master)
+```
+
+*Explications*:
+_Le rebase interactif permet d'enregistrer un suite de manipulation de commit dans un seul fichier texte._ 
+_Le fichier texte qui reprend tels quels tous les commits concernés (et donc qui ne fait rien)_ 
+_est préparé par la commande `-i` de la commande_ `git rebase`
+
+_Vous pouvez ensuite modifier ce fichier dans votre editeur favori (ou pas) (à régler par `git config`) pour décrire_
+_votre intention (réordonner, changer le message, fusionner, ...) sur l'ensemble des commits_
+
+_Quand votre édition est terminée, git reprend la main est exécute chacune de vos opérations. Il est possible_
+_(bien que très rare) que des conflits apparaissent à ce moment-là. Les_
+_commandes habituelles de correction accompagnées des commandes :_
+```bash
+git rebase --continue # pour poursuivre le processus
+git rebase --abort # pour tout abandonner
+```
+_vous permettront de résoudre ces problèmes exceptionnels_.
+
+Application:
+
+```bash
+git rebase -i $(git merge-base HEAD officiel/master)
+```
+Vous devez obtenir dans un éditeur de texte la liste des commits opéré depuis le
+début du développement sous cette forme (c'est un exemple : le nombre de lignes
+peut varier) :
+
+```bash
+pick eb8cbec modif 1
+pick 83eb79e modif 2
+
+# Rebase 5ffd074..83eb79e onto 5ffd074 (2 commands)
+#
+# Commands:
+# p, pick <commit> = use commit
+# r, reword <commit> = use commit, but edit the commit message
+# e, edit <commit> = use commit, but stop for amending
+# s, squash <commit> = use commit, but meld into previous commit
+# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
+#                    commit's log message, unless -C is used, in which case
+#                    keep only this commit's message; -c is same as -C but
+#                    opens the editor
+# x, exec <command> = run command (the rest of the line) using shell
+# b, break = stop here (continue rebase later with 'git rebase --continue')
+# d, drop <commit> = remove commit
+# l, label <label> = label current HEAD with a name
+# t, reset <label> = reset HEAD to a label
+# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
+# .       create a merge commit using the original merge commit's
+# .       message (or the oneline, if no original merge commit was
+# .       specified); use -c <commit> to reword the commit message
+#
+# These lines can be re-ordered; they are executed from top to bottom.
+#
+# If you remove a line here THAT COMMIT WILL BE LOST.
+#
+# However, if you remove everything, the rebase will be aborted.
+#
+```
+
+Vous pouvez réorganiser tous les commits (changer l'ordre, fusionner) en
+changeant la commande pick au début de chaque ligne. L'idée ici est de fusionner
+toutes les lignes avec la première en remplaçant le 'pick' à partir de la ligne
+2 par `fixup`. Optionnellement, vous pouvez reformuler le message de commit
+(commande `reword` sur la première ligne).
+
+Vous construirez par exemple :
+```bash
+reword eb8cbec Correctif: Api - gestion des formation
+fixup 83eb79e modif 2
+...
+```
+
+Quand vous sortez de l'éditeur, git effectue toutes les opérations demandées.
+
+À ce niveau-là de la procédure :
+
+* vous avez un seul commit pour l'ensemble du correctif proposé ;
+
+* toutes les différences entre officiel/master et votre branche locale sont
+  signifiantes.
+
+##### Étape 4 :
+Vous pouvez maintenant pousser votre branche locale sur votre dépôt personnel
+(vers une branche de même nom):
+
+```bash
+  git push --set-upstream perso ma_branche
+```
+
+Si vous avez déjà fait cette opération auparavant il est possible que le push
+soit refusé (car le rebase a modifié des commits qui avaient déjà été poussés).
+Dans ce cas l'option `--force` du push vous permette de passer outre, mais
+assurez-vous avant d'être le seul à travailler sur cette branche.
+
+##### Etape 5 : La dernière étape se passe sur le site [scodoc.org/git](https://scodoc.org/git/)
+
+* Identifiez-vous
+
+* Placez-vous sur la branche nouvellement créée
+
+* À l'aide de l'interface du serveur, vous pouvez comparer l'état de votre
+  branche par rapport au master officiel, et si cela vous convient, il vous reste à formuler
+  une demande d'intégration (*pull request*). En remplissant les informations demandées.
+
+## Tests et tests unitaires
 
 Voir [TestsScoDoc](TestsScoDoc.md)
 

docs/GuideInstallDebian11.md

@@ -138,6 +138,7 @@ Puis créer un dossier `/etc/systemd/system/redis.service.d` contenant le fichie
     ProtectKernelTunables=no
     ProtectKernelModules=no
     ReadWritePaths=
+    ReadOnlyDirectories=
 
 Ensuite 
 

docs/Internals.md

@@ -0,0 +1,75 @@
+#  Code de ScoDoc 9
+
+Quelques informations pour les développeurs.
+
+ - le code est écrit en Python 3.9 (passage à 3.10 prévu en 2022).
+ - le code doit être formatté par [black](https://pypi.org/project/black/) qui
+   est normalement intégré à votre éditeur (VSCode et PyCharm sont deux choix
+   judicieux).
+ - outre Python, les principaux composants logiciels sont:
+    - [Flask](https://flask-sqlalchemy.palletsprojects.com/en/2.x/): le
+      framework Web, dont on utilise notamment:
+        - l'ORM [SQLAlchemy](https://www.sqlalchemy.org/)
+        - les templates [Jinja2](https://jinja.palletsprojects.com/en/3.0.x/)
+    - [Postgresql](https://www.postgresql.org/)
+    - [Redis](https://redis.io/) cache persistant
+    - [NGINX](https://www.nginx.com/) serveur Web frontal
+    - [gunicorn](https://gunicorn.org/) WSGI HTTP server
+    - et bien sûr Linux (Debian) et systemd.
+   
+# Principaux objets
+
+Les objets manipulés par ScoDoc sont pour la plupart stockés en base postgres et
+accédé soit directement en SQL (anciennes parties de ScoDoc), soit à travers
+l'ORM SQLAlchemy (recommandé pour tout nouveau code).
+
+Les modèles correspondant sont déclarés dans `/opt/scodoc/app/models/`.
+
+Principales classes (le nom de certaines classes Python est donné en
+`CaractèresCommeCa`).
+
+ - Étudiants (classe `Identite`): nom, codes INE/NIP, etc
+ - Formations: programmes pédagogiques, contenant
+    - Unités d'Enseignement (`UniteEns`);
+    - Matières et Modules (`Module`, avec son type standard, bonus, ressources
+      ou SAÉ).
+ - FormSemestre: instanciation d'une session de formation, avec un programme
+   pédagogique donné (Formation), les dates de début et fin, des étudiants
+   inscrits, des responsables, divers codes, et les ModuleImpl mis en œuvre.
+ - ModuleImpl: la mise en place d'un module pédagogique (le ModuleImpl est au
+   Module ce que le FormSemestre est à la Formation): lié à un module, avec un
+   enseignant responsable et des étudiants inscrits.
+ - Inscriptions: tables d'association avec codes et/ou état (démission,
+   défaillant): FormsemestreInscription ModuleImplInscription.
+
+# Vues et décorateurs
+
+Une vue ordinaire (Web) pourrait ressembler à cela. Noter la présence de
+décorateurs:
+
+ - `@scodoc` récupère le département (présent dans l'URL) et initialise quelques
+   trucs;
+ - `@permission_required`: permet de contrôler l'accès, en se basant sur les
+   permissions définies dans la classe `Permission`.
+
+```
+@bp.route("/un_exemple")
+@scodoc
+@permission_required(Permission.ScoChangeFormation)
+def un_exemple():
+    # Récupérer le ou les arguments: exemple avec formation_id
+    formation_id = int(request.args["formation_id"])
+    # Charger le ou les objets utilies:
+    formation = models.Formation.query.get(
+        formation_id=formation_id
+    ).first_or_404()
+    # Effectuer au besoin un traitement
+    resultat = ...
+    # Afficher le résultat
+    return render_template( 
+        "exemple_template.html", 
+        resultat=resultat, # par exemple
+        formation=formation,
+        ... # etc
+    )
+```

docs/ParametrageBulletins.md

@@ -96,10 +96,42 @@ Le balisage XML est celui de [ReportLab](http://www.reportlab.com/) (intra-parag
 ###  Logos 
 Une balise supplémentaire est interprétée par ScoDoc pour insérer des logos (images).
 
-Les logos doivent être des images au format JPEG (extension `.jpg` uniquement), placées dans le répertoire `.../logos/`, et nommées `logo_xxx.jpg`.
+Les logos sont des images au format JPEG (extension `.jpg` ou `.jpeg`) ou PNG (expension `.png`), téléversés sur le serveur scodoc et intégrables dans les documents html ou pdf.
 
-La balise `<logo name="xxx" width="44mm" height="22mm" valign="+5mm"/>`, placée dans un paragraphe, insère alors le logo `xxx` avec les dimensions indiquées. Le paramètre `valign` règle le positionnement vertical par rapport à la ligne de texte courante.
+Principes généraux : 
 
+* Un logo est désigné par un identifiant (nom) et peut être défini soit globalement, soit pour un département;
+
+* le nom d'un logo est exclusiement composé de caractères alphanumériques ou du caractère '`-`';
+
+* les logos définis globalement sont accessibles pour tous les départements. Toutefois, si un logo de même nom est également présent dans un département,
+, c'est le logo du département qui sera utilisé en lieu et place de logo global;
+
+* les logos de nom '`header`' et '`footer`' définis globalement ne peuvent être supprimés (mais peuvent être redéfinis).
+
+L'enregistrement, la modification ou la suppression d'un logo peut être réalisé via la page de configuration qui est accessible aux 
+administrateurs Scodoc depuis la page d'accueil.
+
+Ce formulaire comporte une section pour les définitions globales plus une section par département.
+
+Une section présente la liste des logos avec leurs propriétés (la dimension est donnée à titre indicatif quand elle est disponible). 
+
+Pour chaque logo, les actions diponibles sont :
+
+* Le remplacement de l'image existante par un nouveau fichier ;
+
+* la suppression du logo (sauf pour `header`et `footer`dans la section globale) ;
+
+* l'ajout d'un nouveau logo dans une section (global ou département) et indiquant le nom.
+
+*NB*. Quelle que soit l'opération effectuée, le nom du fichier téléversé n'a aucune importance
+(Seul le nom indiqué dans le formulaire est pris en compte et le format du fichier est déduit des données propres du fichier)
+
+La balise `<logo name="xxx" width="44mm" height="22mm" valign="+5mm"/>`, placée dans un paragraphe, insère le logo de nom `xxx` avec les dimensions indiquées.
+Le paramètre `valign` règle le positionnement vertical par rapport à la ligne de texte courante.
+
+Notez qu'il est possible de ne préciser que l'une des deux dimensions hauteur ou largeur. 
+Dans ce cas, la dimension manquante est déduite du ratio (rapport hauteur/largeur) de l'image originale.
 Voir un exemple d'utilisation plus bas.
 
 

docs/PublicationEtudiants.md

@@ -7,7 +7,7 @@ Pour communiquer aux étudiants leurs réultats, plusieurs solutions:
  - Envoi des bulletins (pdf) par mail (c'est facile depuis le menu "Notes").
 
  - Publication sur un autre site Web: typiquement l'ENT de l'établissement, ou un mini-site dédié. 
-    - Pour interfacer un ENT, [voir l'API](ScoDocAPI.md).
+    - Pour interfacer un ENT, [voir l'API](ScoDoc9API.md).
     - Plusieurs collègues ont développé des mini-sites pour publier les notes (accès protégé par CAS ou autre). Ces codes ne font pas stricto censu partie de ScoDoc. Quelques exemples en PHP sont distribués dans le répertoire `misc/PublicationBulletins` ([voir ici](https://scodoc.org/git/viennet/ScoDoc/src/branch/master/misc/PublicationBulletins)).
     - Plus récemment (2020), des collègues de l'IUT de Mulhouse ont développé un mini-portail complet: [Scodoc_Notes](https://github.com/SebL68/Scodoc_Notes) (github), [historique](https://notes.iutmulhouse.uha.fr/maj.php).
 

docs/RelationsEntreprises.md

@@ -8,6 +8,7 @@ Les utilisateurs interrogés insistent sur leur souhait d'avoir une interface si
 ## Principales fonctionnalités
 
 L'application, intégrée à ScoDoc, fournira:
+
 - Saisie et gestion des entreprises
 - Saisie et gestion des offres de stage et d'apprentissage
 - Envoi des offres aux responsables de formations

docs/SauvegardesBases.md

@@ -1,23 +1,43 @@
 
 
 #  Mise en place de sauvegardes des bases de données ScoDoc 9
-Il est ***vivement recommandé*** de mettre en place une stratégie de sauvegarde permettant de rétablir le service en minimisant les pertes de données à la suite d'un accident majeur mais probable comme: crash de disque dur, bug, vol du serveur, incendie...
+Il est ***vivement recommandé*** de mettre en place une stratégie de sauvegarde
+permettant de rétablir le service en minimisant les pertes de données à la suite
+d'un accident majeur mais probable comme: crash de disque dur, bug, vol du
+serveur, incendie...
 
 Nous recommandons d'agir à deux niveaux:
 
- * sauvegarde des bases de données postgresql: dump des bases dans des fichiers. Le script donné ci-dessous peut se charger de gérer cela.
+ * sauvegarde des bases de données postgresql: dump des bases dans des fichiers.
+   Le script donné ci-dessous peut se charger de gérer cela.
 
- * sauvegarde du système complet (et de ses disques durs): la forme dépend de l'environnement (machine virtuelle ou non...). Dans tous les cas, les données doivent être sauvegardées dans une salle (voire un bâtiment) différente de celle abritant le serveur ScoDoc (vols ou incendies). Typiquement, une sauvegarde quotidienne (nocturne) est suffisante. 
+ * sauvegarde du système complet (et de ses disques durs): la forme dépend de
+   l'environnement (machine virtuelle ou non...). Dans tous les cas, les données
+   doivent être sauvegardées dans une salle (voire un bâtiment) différente de
+   celle abritant le serveur ScoDoc (vols ou incendies). Typiquement, une
+   sauvegarde quotidienne (nocturne) est suffisante. 
 
-Notons que ScoDoc sauvegarde de nombreuses informations sous le répertoire `/opt/scodoc-data` (en particulier les photos, les documents archivés et divers réglages): *il est absolument nécessaire de sauvegarder aussi ce répertoire*, en plus des bases de données SQL.
+Notons que ScoDoc sauvegarde de nombreuses informations sous le répertoire
+`/opt/scodoc-data` (en particulier les photos, les documents archivés et divers
+réglages): *il est absolument nécessaire de sauvegarder aussi ce répertoire*, en
+plus des bases de données SQL.
 
 
-###  Dump des bases de données 
-Le script `backup_db9` (fourni dans le répertoire `/opt/scodoc/tools/backups`) peut être utilisé pour effectuer des sauvegardes automatisées des bases de données SQL. Les données sont extraites de la base et écrites sur le disque local du serveur, qui doit bien entendu être sauvegardé par d'autres moyens, comme indiqué ci-dessus.
+##  Dump des bases de données 
+Le script `backup_db9` (fourni dans le répertoire `/opt/scodoc/tools/backups`)
+peut être utilisé pour effectuer des sauvegardes automatisées des bases de
+données SQL. Les données sont extraites de la base et écrites sur le disque
+local du serveur, qui doit bien entendu être sauvegardé par d'autres moyens,
+comme indiqué ci-dessus.
 
-Le script `backup_db9` permet de conserver des sauvegardes de chaque heure durant les 48 (par défaut) dernières heures, des sauvegardes quotidiennes des 40 derniers jours, hebdomadaires des 30 dernières semaines, et mensuelles des 200 derniers mois (tout ceci est paramétrable dans le script `/opt/scodoc/tools/backups/backup_rotation.sh`).
+Le script `backup_db9` permet de conserver des sauvegardes de chaque heure
+durant les 48 (par défaut) dernières heures, des sauvegardes quotidiennes des 40
+derniers jours, hebdomadaires des 30 dernières semaines, et mensuelles des 200
+derniers mois (tout ceci est paramétrable dans le script
+`/opt/scodoc/tools/backups/backup_rotation.sh`).
 
-Par défaut, les fichiers de sauvegardes sont créés dans le répertoire de l'utilisateur `postgres` (actuellement `/var/lib/postgresql/`).
+Par défaut, les fichiers de sauvegardes sont créés dans le répertoire de
+l'utilisateur `postgres` (actuellement `/var/lib/postgresql/`).
 
 
 En tant que `root` sur le serveur, faire:
@@ -34,10 +54,14 @@ et ajouter:
 
 
 
-###  En cas de problème: restaurer la base à partir d'une sauvegarde 
+##  En cas de problème: restaurer la base à partir d'une sauvegarde 
 <img src="/img/alert.png" style="vertical-align: bottom; margin:0 0 0 0;" alt="/!\" /> Attention, certaines informations sont stockées dans des fichiers et non dans la base de données: configuration du logiciel, photos des étudiants. Ce paragraphe ne traite que de la restauration à de la base de données.
 
- 1. Choisir la sauvegarde à utiliser, en fonction de la date à partir de laquelle on a fait une erreur (eg suppression non intentionnelle d'un semestre...). Le fichier se trouve sous `/var/lib/postgresql/SCODOC-BACKUPS`où `XXX` est concerné. Utiliser par exemple `ls -lrt` pour visualiser les sauvegardes triées par date.
+ 1. Choisir la sauvegarde à utiliser, en fonction de la date à partir de
+    laquelle on a fait une erreur (eg suppression non intentionnelle d'un
+    semestre...). Le fichier se trouve sous
+    `/var/lib/postgresql/SCODOC-BACKUPS`où `XXX` est concerné. Utiliser par
+    exemple `ls -lrt` pour visualiser les sauvegardes triées par date.
 
  1. Copier le fichier de sauvegarde choisi et le décomprimer; par exemple: 
 
@@ -54,22 +78,48 @@ et ajouter:
 systemctl stop scodoc9  # arret du serveur
 su postgres
 dropdb SCODOC # <<< votre base production
-pg_restore -C -d scodoc /tmp/SCODOC_pgdump # <<<
+pg_restore -C -d scodoc /tmp/XXX # (nom de la BDD en majuscule)
 exit # retour a l'utilisateur root
-systemctl start scodoc # relance ScoDoc
+systemctl start scodoc9 # relance ScoDoc
 ```
 
 Attention: s'il y a eu des mise à jour du logiciel entre temps, il peut arriver
-que la base sauvegardée nécessite une migration. Arrêtez le sservice scodoc9,
+que la base sauvegardée nécessite une migration. Arrêtez le service scodoc9,
 puis, en tant qu'utilisateur `scodoc`, lancer les commandes suivantes: 
 
     cd /opt/scodoc
     source venv/bin/activate
     flask db upgrade
 
-puis relancer le service (`systemctl start scodoc` comme root).
+puis relancer le service (`systemctl start scodoc9` comme root).
 
 
+## Déplacement de toute une installation
+Les scripts ci-dessus ne se chargent que de la base de données SQL.
 
+Pour créer une sauvegarde complète d'une installation, vous pouvez utiliser le
+script
+
+    tools/save_scodoc9_data.sh /tmp/sauvegarde-scodoc.tgz
+
+Ce script va générer une archive (`tar`, format `.tgz`) contenant non seulement
+la base de données SQL mais aussi tous les fichiers générés par votre ScoDoc:
+photos, configurations locales, archives, PV de jurys, logos, etc (tout ceci
+étant stocké sous `/opt/scodoc-data`).  
+
+Attention à l'espace disque: le répertoire destination (`/tmp`dans l'exemple
+ci-dessus) doit avoir de l'espace (sinon utilisez un autre répertoire dans
+lequel l'utilisateur `scodoc` puisse écrire, ou montez un autre disque. La
+commande `df -h`est votre amie).
+
+Pour restaurer ce type de sauvegarde, sur une autre machine (ou plus tard sur la
+même), transférer le fichier généré (`/tmp/sauvegarde-scodoc.tgz`) dans
+l'exemple ci-dessus) et utiliser
+
+    tools/restore_scodoc9_data.sh /tmp/sauvegarde-scodoc.tgz
+
+(Note: la sauvegarde s'effectue comme utilisateur `scodoc`, en revanche le
+rechargement doit se faire en tant que `root` car il faut évidemment arrêter et
+relancer le service).
  
 

docs/ScoDocAPI.md

@@ -914,8 +914,7 @@ Et un autre exemple en format JSON:
 
 
 ##  En savoir plus 
-Voir l'exemple complet d'utilisation de l'API JSON en Python, dans `misc/example-api-1.py`
-
+Voir exemples d'utilisation de l'API en Python, dans `tests/api/`.
 
 
 

docs/index.md

@@ -85,9 +85,19 @@ Les prochaines versions de ScoDoc (*sous réserve !*):
  - ScoDoc 9.0 : publiée le 19 sept. 2021, version complètement remaniée en
    Python 3/Flask.
 
- - ScoDoc 9.1 : octobre 2021 gestion du bachelor (BUT)
- 
- - ScoDoc 9.2 : décembre 2021 nouvelles fonctionnalités liées au BUT.
+ - ScoDoc 9.1 : décembre 2021 gestion du bachelor (BUT)
+    - type de formation BUT
+    - distinction SAE/ressources
+    - poids (coefs) des évaluations, affichage, édition
+    - coefs de modules (ressources, SAE): affichage et édition dans ScoDoc
+    - calculs moyennes modules et vérification conformité
+    - calcul des moyennes d'UE
+    - bulletin de note v1
+
+ - ScoDoc 9.2 : fin 2021 ou début 2022 nouvelles fonctionnalités liées au BUT
+    - tenue des jurys de S1
+    - gestion des parcours (pour la mise en place des semestre)
+    - import Orébut avec gestion adaptation locale (à l'étude)
 
 <br> 
 

mkdocs.yml

@@ -18,7 +18,6 @@ nav:
     - 'Interfaces SI': InterrogationPortail.md
     - 'Publication des notes': PublicationEtudiants.md
     - 'Export Apogée': ScoDocApogee.md
-    - 'API': ScoDocAPI.md
 
   - Association: 
     - 'Association 1901': AssociationScoDoc.md
@@ -27,6 +26,8 @@ nav:
   - Développement:
     - 'Git': https://scodoc.org/git
     - 'Guide Développeurs': GuideDeveloppeurs.md
+    - 'API (interfaçages autres logiciels)': ScoDoc9API.md
+
 
   - FAQ: FAQ.md