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