doc: Début de la nouvelle documentation avec Sphinx

1 files changed, 143 insertions, 0 deletions

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
+
+    <span id="1" date="16/10/2017" rawix="9" rawlen="1">
+    <description>Semaine 42, Semaine commençant le 16/10/2017</description>
+    <title>42</title>
+    <alleventweeks>NNNNNNNNYNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN</alleventweeks>
+    <day id="0">
+    <name>lundi</name>
+    <row id="0" />
+    <row id="1" />
+    <row id="2" />
+    <row id="3" />
+    <row id="4" />
+    <row id="5" />
+    <row id="6" /></day>
+    <day id="1">
+    <name>mardi</name>
+    <row id="0" />
+    <row id="1" />
+    <row id="2" />
+    <row id="3" />
+    <row id="4" />
+    <row id="5" /></day>
+    <day id="2">
+    <name>mercredi</name>
+    <row id="0" />
+    <row id="1" />
+    <row id="2" />
+    <row id="3" />
+    <row id="4" />
+    <row id="5" />
+    <row id="6" /></day>
+    <day id="3">
+    <name>jeudi</name>
+    <row id="0" />
+    <row id="1" />
+    <row id="2" />
+    <row id="3" />
+    <row id="4" />
+    <row id="5" /></day>
+    <day id="4">
+    <name>vendredi</name>
+    <row id="0" />
+    <row id="1" />
+    <row id="2" />
+    <row id="3" />
+    <row id="4" />
+    <row id="5" /></day></span>
+
+Vous voyez donc la date de début, le numéro de semaine, et la
+mystérieuse valeur ``<alleventweeks>``. Il s’agit d’un identifiant de
+semaine. La propriété ``id`` du ``<span>`` 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
+``<alleventweeks>`` comme clé, et le premier jour de la semaine comme
+valeur.
+
+Les cours
+=========
+Voici un exemple de cours :
+
+.. code:: xml
+
+    <event id="351687" timesort="07450945" colour="BEA7B8" ecs="4" ecc="11" er="0" scb="1">
+    <day>1</day>
+    <prettytimes>07:45-09:45 COURS/TD</prettytimes>
+    <starttime>07:45</starttime>
+    <endtime>09:45</endtime>
+    <category>COURS/TD</category>
+    <prettyweeks></prettyweeks>
+    <rawweeks>NNNNNNNNYNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN</rawweeks>
+    <resources>
+    <module title="Matière">
+    <item>EDINF3F1 - Algorithmique et programmation</item></module>
+    <group title="Groupe">
+    <item>L2 Info s1 TDA4</item></group>
+    <room title="Salle">
+    <item>1TP1-B08bis</item></room></resources></event>
+
+Les différents éléments sont :
+
+================= ===================== =============================
+Donnée indiquée   Balise correspondante Plusieurs valeurs possibles ?
+================= ===================== =============================
+Nom du cours      ``<module>``          Oui
+Groupes concernés ``<group>``           Oui
+Salles            ``<room>``            Oui
+Type de cours     ``<category>``        Non
+Heure de début    ``<starttime>``       Non
+Heure de fin      ``<endtime>``         Non
+Jour              ``<day>``             Non
+Semaine           ``<rawweeks>``        Non
+Remarque          ``<notes>``           Non
+================= ===================== =============================
+
+Quand une donnée peut prendre plusieurs valeurs à la fois, les
+différentes valeurs se trouvent dans des balises
+``<item>``. 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 ``<rawweeks>``, on retrouve le début de la semaine
+correspondante à l’aide du :ref:`dictionnaire des semaines
+<ref-week-dict>`, et on ajoute autant de jours qu’indiqué par la
+balise ``<day>``.