Enhance documentation, especially for Windows installations.

README.md

@@ -1,9 +1,8 @@
 # scodoc-cohortes
 
-Visualisation des cohortes de BUT depuis scodoc
+*Visualisation des cohortes de BUT depuis scodoc*
 
-Ce programme utilise l'API pour générer des graphes de Sankey permettant
+Ce programme utilise l'API pour générer des graphes de Sankey permettant de visualiser le devenir d'une cohorte.
-de visualiser le devenir d'une cohorte.
 
 La notion de cohorte devient difficile à traiter lorsqu'on considère
 l'existence de passerelles permettant d'entrer à n'importe quel année
@@ -38,17 +37,19 @@ Il existe un dernier type (qui tombe dans le 5 ou le 6 actuellement), c'est
 le cas d'un élève en BUT3 qui ne valide pas le BUT3, a validé le BUT2, et
 partirait dans une autre filière après. Le cas paraît beaucoup plus douteux que le deuxième type et est pour le moment classé en échec.
 
-## Installation
+## Installation (Linux et MacOS)
 
 Créer un virtualenv:
 
 ```bash
 python3 -m venv venv
 source venv/bin/activate
-sudo apt-get install libcairo-dev
+sudo apt install libcairo-dev
 ```
 (n'importe quelle version de python récente fera l'affaire).
 
+Si vous êtes sur un système qui n'est pas de la famille Debian/Ubuntu, il faudra sans doute remplacer la dernière ligne par votre installeur de paquets préféré. Cette opération n'est à faire qu'une seule fois par machine.
+
 Puis installer les composants suivants dans ce virtualenv:
 
 ```
@@ -63,16 +64,35 @@ SCODOC_USER=un_utilisateur_api
 SCODOC_PASSWORD=son_mot_de_passe
 ```
 
+## Installation (Windows)
+
+Exécuter un terminal depuis le répertoire où est installé le programme. Les commandes à taper dans l'interpréteur de commandes *PowerShell* sont :
+
+```powershell
+python.exe -m venv venv
+venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+```
+Puis indiquer votre configuration ScoDoc dans le fichier `.env`:
+
+```bash
+SCODOC_SERVER=https://votre.serveur.fr
+SCODOC_USER=un_utilisateur_api
+SCODOC_PASSWORD=son_mot_de_passe
+```
+
+Pycairo ne devrait pas s'installer. Si vous savez installer un pycairo fonctionnel pour Windows, n'hésitez pas à nous proposer de le rajouter à ces instructions.
+
 ### Note pour les développeurs
 
 Pour mettre à jour le fichier `requirements.txt`, lancer (après avoir activé
 l'environnement python)
 ```py
-pip freeze > requirements.txt
+pip freeze|sed -e '/pycairo/ s/$/; platform_system != "Windows"/g' > requirements.txt
 ```
 ## Usage
 
-Après ouverture du terminal:
+Après ouverture du terminal (une seule fois par terminal):
 
 ```bash
 source venv/bin/activate
@@ -88,15 +108,21 @@ Puis
 
 ### get.py
 
-Le programme principal. Il prend en argument des acronymes de département (par exemple GEA ou INFO) et fabrique un graphe comportant les formations BUT de ce département (ou ces départements dans le même graphe, s'ils sont plusieurs sur la ligne de commande).
+C'est l'exécutable. Il prend en argument des acronymes de département (par exemple GEA ou INFO) et fabrique un graphe comportant les formations BUT de ce département (ou ces départements dans le même graphe, s'ils sont plusieurs sur la ligne de commande).
 
 Il faut un environnement virtuel pour que soient accessibles les bibliothèques Python pycairo, drawsvg, requests. A priori libcairo est optionnel, mais le graphe marchera moins bien sans. La bibliothèque (système) `libcairo2` doit aussi être installée (`apt install libcairo-dev` ou équivalent).
 
 On peut rajouter l'option `--techno` pour n'avoir que les bacs technos.
 
+Liste complète des options : 
+
+ * `--techno` : ne sélectionne que les bacs technos
+ * `--base` *year* : prend la cohorte constituée de tous les élèves qui ont touché le S1 ou le S2 dans l'année *year*, le S3 ou le S4 dans l'année *year+1*, et le S5 ou le S6 dans l'année *year+2*.
+ * *dept1* (acronyme d'un département, suivi éventuellement d'autres acronymes de département) : sélectionne les départements mentionnés. Si aucun département n'est mentionné, donne l'aide.
+
 ### redirect.csv
 
-Certains élèves ne reçoivent jamais de décision de jury lorsqu'ils quittent la cohorte, tout en n'étant pas démissionnaires. Ce sont des erreurs administratives, mais il est possible d'indiquer un *résultat de jury* fictif pour ces élèves. La plupart du temps, ce sont des élèves qui abandonnent la formation, et il suffit de leur donner le résultat NAR ou DEM. Dans d'autres cas, ça peut être des élèves en attente de décision parce que le jury n'a pas encore eu lieu, mais on sait déjà quel sera l'issue du jury (par exemple des notes élevés et un stage qui se déroule bien, ou au contraire pas de stage trouvé au mois de septembre).
+Certains élèves ne reçoivent jamais de décision de jury lorsqu'ils quittent la cohorte, tout en n'étant pas démissionnaires. Ce sont des erreurs administratives, mais il est possible d'indiquer un *résultat de jury* **fictif** pour ces élèves. La plupart du temps, ce sont des élèves qui abandonnent la formation, et il suffit de leur donner le résultat NAR ou DEM. Dans d'autres cas, ça peut être des élèves en attente de décision parce que le jury n'a pas encore eu lieu, mais on sait déjà quel sera l'issue du jury (par exemple des notes élevés et un stage qui se déroule bien, ou au contraire pas de stage trouvé au mois de septembre).
 
 **Format :** format CSV avec virgule comme séparateur. Les lignes vides ou commençant par # sont ignorées.
 
@@ -107,7 +133,7 @@ Certains élèves ne reçoivent jamais de décision de jury lorsqu'ils quittent
 
 ### theme.csv
 
-Possibilité de choisir les couleurs pour chacune des catégories.
+Ce fichier offre la ossibilité de choisir les couleurs pour chacune des catégories.
 
 **Format :** format CSV avec virgule comme séparateur. Les couleurs sont au format de sankeymatic.com, soit le format hexadécimal d'HTML sauf la catégorie TRANSPARENT qui vaut #FFFFFF.0 (blanc transparent). Les catégories sont `+DUT`, `QUIT`, `SUCCESS`, `NORMAL`, `FAIL`, `OLD`, `NEW`, `TRANSPARENT`, `RED`.
 
@@ -123,8 +149,16 @@ Possibilité de choisir les couleurs pour chacune des catégories.
 
 ### <dept>.json
 
+Ce fichier permet de configurer plus finement le graphique pour le département (ou la combinaison de département, séparés par des `_`) indiqué dans son nom de fichier.
+
+**Format :** format JSON (utiliser un éditeur qui sait repérer les erreurs de format est recommandé).
+
+**Liste des clés :** à venir.
+
 ### <dept>.svg
 
+Ce fichier est la sortie du programme. C'est un graphique au format SVG, facile à incorporer dans des pages Web ou autres programmes de traitement de texte.
+
 ### best-<dept>.json
 
-Ce fichier contient le résultat d'une recherche heuristique pour avoir un graphe meilleur. Il peut être supprimé si le graphe ne s'améliore pas sur des lancements successifs. Il peut aussi être modifié à la main.
+Ce fichier contient le résultat d'une recherche heuristique pour avoir un graphe visuellement plus satisfaisant. Il peut être supprimé si le graphe ne s'améliore pas par des lancements successifs. Il peut aussi être modifié à la main. C'est essentiellement l'ordre des balises

requirements.txt

@@ -2,7 +2,7 @@ certifi==2024.8.30
 charset-normalizer==3.4.0
 drawsvg==2.4.0
 idna==3.10
-pycairo==1.27.0
+pycairo==1.27.0;platform_system != "Windows"
 python-dotenv==1.0.1
 requests==2.32.3
 urllib3==2.2.3