From 0eeba2b335807c8c19c2dbfd0463aa4df1375d0e Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 15 Apr 2018 21:46:47 +0200 Subject: doc: Début de la nouvelle documentation avec Sphinx --- Documentation/dev/contribute.rst | 3 + Documentation/dev/internals.rst | 3 + Documentation/dev/roadmap.rst | 20 ++++++ Documentation/dev/xml.rst | 143 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 169 insertions(+) create mode 100644 Documentation/dev/contribute.rst create mode 100644 Documentation/dev/internals.rst create mode 100644 Documentation/dev/roadmap.rst create mode 100644 Documentation/dev/xml.rst (limited to 'Documentation/dev') diff --git a/Documentation/dev/contribute.rst b/Documentation/dev/contribute.rst new file mode 100644 index 0000000..faab4f5 --- /dev/null +++ b/Documentation/dev/contribute.rst @@ -0,0 +1,3 @@ +======================================= +Guide de contribution à celcatsanitizer +======================================= diff --git a/Documentation/dev/internals.rst b/Documentation/dev/internals.rst new file mode 100644 index 0000000..9800d06 --- /dev/null +++ b/Documentation/dev/internals.rst @@ -0,0 +1,3 @@ +========================================= +Fonctionnement interne de celcatsanitizer +========================================= diff --git a/Documentation/dev/roadmap.rst b/Documentation/dev/roadmap.rst new file mode 100644 index 0000000..a7db062 --- /dev/null +++ b/Documentation/dev/roadmap.rst @@ -0,0 +1,20 @@ +================ +Feuille de route +================ + +Version 0.14 +============ + - Optimisation des requêtes en utilisant des fonctionnalités + spécifiques à PostgreSQL si nécessaire + - Remplacement du moteur de templates de Django par Jinja2_. + +.. _Jinja2: http://jinja.pocoo.org/ + +Version 1.0 +=========== + - Paquetage permettant l’installation par ``pip``. + +Futures fonctionnalités +======================= + - Utilisation de l’aggrégat ``TruncWeek`` dès que Django le proposera + (*a priori*, dès la version 2.1). diff --git a/Documentation/dev/xml.rst b/Documentation/dev/xml.rst new file mode 100644 index 0000000..bb2ebd0 --- /dev/null +++ b/Documentation/dev/xml.rst @@ -0,0 +1,143 @@ +================================== +Format des emplois du temps Celcat +================================== + +Avant de pouvoir afficher les emplois du temps, il est nécessaire de +parser les fichiers XML générés par Celcat. + +On a besoin de plusieurs informations concernant le cours : + + - son nom ; + - son type ; + - sa semaine et son jour ; + - son début et sa fin ; + - son commentaire ; + - ses salles ; + - ses groupes ; + +Certaines de ces informations sont triviales à récupérer (comme son +nom, son type, son commentaire…), mais d’autres (telles que son jour +précis) est un peu plus délicat. + +Parser facilement le XML +======================== +Pour traiter le XML facilement, celcatsanitizer utilise la fameuse +librairie BeautifulSoup4. Pour récupérer le fichier, on utilise la +librairie requests. + +Les semaines +============ +La première chose à faire après avoir téléchargé le fichier est de +récupérer la liste des semaines présentes. Les dates sont encodées +d’une manière assez exotique : + +.. code:: xml + + + Semaine 42, Semaine commençant le 16/10/2017 + 42 + NNNNNNNNYNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN + + lundi + + + + + + + + + mardi + + + + + + + + mercredi + + + + + + + + + jeudi + + + + + + + + vendredi + + + + + + + +Vous voyez donc la date de début, le numéro de semaine, et la +mystérieuse valeur ````. Il s’agit d’un identifiant de +semaine. La propriété ``id`` du ```` ne semble pas être +nécessaire pour comprendre le reste du fichier. + +.. _ref-week-dict: + +On va donc créer un tableau des semaines en se servant des +```` comme clé, et le premier jour de la semaine comme +valeur. + +Les cours +========= +Voici un exemple de cours : + +.. code:: xml + + + 1 + 07:45-09:45 COURS/TD + 07:45 + 09:45 + COURS/TD + + NNNNNNNNYNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN + + + EDINF3F1 - Algorithmique et programmation + + L2 Info s1 TDA4 + + 1TP1-B08bis + +Les différents éléments sont : + +================= ===================== ============================= +Donnée indiquée Balise correspondante Plusieurs valeurs possibles ? +================= ===================== ============================= +Nom du cours ```` Oui +Groupes concernés ```` Oui +Salles ```` Oui +Type de cours ```` Non +Heure de début ```` Non +Heure de fin ```` Non +Jour ```` Non +Semaine ```` Non +Remarque ```` Non +================= ===================== ============================= + +Quand une donnée peut prendre plusieurs valeurs à la fois, les +différentes valeurs se trouvent dans des balises +````. celcatsanitizer traîte tous les groupes et toutes les +salles, mais ne lis qu’un seul nom de cours. + +Dans l’exemple donné plus haut, il n’y a pas de champ remarque. + +Pour trouver le jours du cours, on prend la semaine référencée par la +balise ````, on retrouve le début de la semaine +correspondante à l’aide du :ref:`dictionnaire des semaines +`, et on ajoute autant de jours qu’indiqué par la +balise ````. -- cgit v1.2.1