diff options
Diffstat (limited to 'Documentation/dev')
| -rw-r--r-- | Documentation/dev/contribute.rst | 55 | ||||
| -rw-r--r-- | Documentation/dev/roadmap.rst | 20 | ||||
| -rw-r--r-- | Documentation/dev/xml.rst | 147 |
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>``. |