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 From 236df1e91d5b00fcd19a47ba886721951337aa82 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 22 Apr 2018 15:27:45 +0200 Subject: doc: reformulation d’un paragraphe --- Documentation/dev/xml.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'Documentation/dev') diff --git a/Documentation/dev/xml.rst b/Documentation/dev/xml.rst index bb2ebd0..a48a3d7 100644 --- a/Documentation/dev/xml.rst +++ b/Documentation/dev/xml.rst @@ -13,7 +13,7 @@ On a besoin de plusieurs informations concernant le cours : - son début et sa fin ; - son commentaire ; - ses salles ; - - ses groupes ; + - 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 @@ -21,9 +21,13 @@ 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. +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 ============ -- cgit v1.2.1 From 99025660d1d5d36fb374159b505ee29884faaab7 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 22 Apr 2018 15:57:37 +0200 Subject: doc: Guide de contribution --- Documentation/dev/contribute.rst | 52 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) (limited to 'Documentation/dev') diff --git a/Documentation/dev/contribute.rst b/Documentation/dev/contribute.rst index faab4f5..ed6d44e 100644 --- a/Documentation/dev/contribute.rst +++ b/Documentation/dev/contribute.rst @@ -1,3 +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 +`. 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 -- cgit v1.2.1 From 1ca0575a0633d281b9dc2ca10b7c0ad2fded86a7 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 22 Apr 2018 18:42:14 +0200 Subject: doc: finalisation --- Documentation/dev/internals.rst | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 Documentation/dev/internals.rst (limited to 'Documentation/dev') diff --git a/Documentation/dev/internals.rst b/Documentation/dev/internals.rst deleted file mode 100644 index 9800d06..0000000 --- a/Documentation/dev/internals.rst +++ /dev/null @@ -1,3 +0,0 @@ -========================================= -Fonctionnement interne de celcatsanitizer -========================================= -- cgit v1.2.1