aboutsummaryrefslogtreecommitdiff
path: root/Documentation/dev
diff options
context:
space:
mode:
authorAlban Gruin2018-04-25 21:26:03 +0200
committerAlban Gruin2018-04-25 21:26:03 +0200
commit54c5dbb98293acea9b470808e5a35e99c004f265 (patch)
tree7fb350d07e2f2a4d687b00fd034e638bd02f8526 /Documentation/dev
parent772caa72ce7f80bfeb5fbb1d05b57838dafd48c3 (diff)
parent5488a93bf2e04d2f19e287186011dcbb436a238b (diff)
Merge branch 'stable/0.13.z' into prod/pa1ch/0.y.z
Diffstat (limited to 'Documentation/dev')
-rw-r--r--Documentation/dev/contribute.rst55
-rw-r--r--Documentation/dev/roadmap.rst20
-rw-r--r--Documentation/dev/xml.rst147
3 files changed, 222 insertions, 0 deletions
diff --git a/Documentation/dev/contribute.rst b/Documentation/dev/contribute.rst
new file mode 100644
index 0000000..ed6d44e
--- /dev/null
+++ b/Documentation/dev/contribute.rst
@@ -0,0 +1,55 @@
+=======================================
+Guide de contribution à celcatsanitizer
+=======================================
+
+.. _ref-list:
+
+Liste de diffusion
+==================
+Le développement se déroule sur la liste de diffusion
+``celcatsanitizer [arobase] framalistes [point] org``. Attention, les
+messages de cette liste sont archivés publiquement.
+
+Dépôt
+=====
+Le dépôt se trouve à l’adresse
+https://git.pa1ch.fr/alban/celcatsanitizer.git. Clonez-le en local à
+l’aide de git_.
+
+Bien que la forge logicielle supporte les *issues* et les *pull
+requests*, ces fonctionnalités ne sont pas utilisées pour le
+développement de celcatsanitizer.
+
+.. _git: https://git-scm.com/
+
+Sur quelle branche travailler ?
+===============================
+Pour réaliser des correctifs de bogue dans une version stable,
+effectuez vos changements sur la branche ``master``. Ne rajoutez pas
+de nouvelle fonctionnalité ou ne changez pas la structure de la base
+de données sur cette branche.
+
+Pour rajouter de nouvelles fonctionnalités, effectuez vos changements
+sur la branche ``futur``. Contactez l’équipe de développement pour
+avoir un avis.
+
+Si jamais vous voulez corriger un bogue sur la branche ``futur`` et
+que la branche ``master`` est aussi affecté, n’hésitez-pas à le
+rétro-porter.
+
+N’oubliez pas de `signer vos commits`_ (avec ``Signed-off-by:``). Si
+vos patches sont conséquents, n’hésitez pas à rajouter votre nom au
+*copyright*.
+
+.. _signer vos commits:
+ https://git-scm.com/docs/git-commit#git-commit--s
+
+Envoyer les patches
+===================
+Envoyez vos patches sur :ref:`la liste de diffusion
+<ref-list>`. Formattez vos patches avec git-format-patches_ et
+envoyez-les avec git-send-email_. Rebasez vos changements si
+nécessaire.
+
+.. _git-format-patches: https://git-scm.com/docs/git-format-patch
+.. _git-send-email: https://git-scm.com/docs/git-send-email
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..a48a3d7
--- /dev/null
+++ b/Documentation/dev/xml.rst
@@ -0,0 +1,147 @@
+==================================
+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 récupérer les fichiers à distance, celcatsanitizer utilise la
+bibliothèque requests_, et se sert de BeautifulSoup4_ pour parser les
+fichiers XML.
+
+.. _BeautifulSoup4:
+ https://www.crummy.com/software/BeautifulSoup/bs4/doc/
+.. _requests: http://docs.python-requests.org/en/master/
+
+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>``.