Merge branch 'futur'

6 files changed, 421 insertions, 0 deletions

diff --git a/Documentation/usage/commands/cleancourses.rst b/Documentation/usage/commands/cleancourses.rst
new file mode 100644
index 0000000..6e4f152
--- /dev/null
+++ b/Documentation/usage/commands/cleancourses.rst
@@ -0,0 +1,20 @@
+================
+``cleancourses``
+================
+
+``cleancourses`` permet d’effacer des cours présents dans la base de
+données. Il peut soit s’agir de tous les cours ou des cours d’une
+seule source.
+
+**ATTENTION : cette commande est irréversible.**
+
+Utilisation
+===========
+
+.. code:: shell
+
+   $ ./manage.py cleancourses [--source id]
+
+``--source`` permet de spécifier la suppression des cours provenant
+d’une seule source. ``id`` correspond à l’ID de la source, trouvable
+à l’aide de la commande :doc:`listtimetables`.
diff --git a/Documentation/usage/commands/listtimetables.rst b/Documentation/usage/commands/listtimetables.rst
new file mode 100644
index 0000000..94485b6
--- /dev/null
+++ b/Documentation/usage/commands/listtimetables.rst
@@ -0,0 +1,26 @@
+==================
+``listtimetables``
+==================
+
+``listtimetables`` affiche tous les emplois du temps présents dans la
+base de données, avec leur nom, leur source et leur identifiant
+interne dans la base de données.
+
+Utilisation
+===========
+.. code:: shell
+
+    $ ./manage.py listtimetables
+
+Format de sortie
+================
+Cette commande affiche les sources avec leur URL et leur ID interne
+(utilisable avec la commande :doc:`cleancourses`), ainsi que la liste
+des emplois du temps associés à cette source.
+
+Exemple de sortie
+-----------------
+::
+
+    L1 Info, L1 Miashs      : https://edt.univ-tlse3.fr/FSI/2017_2018/L1/L1_SN/g222621.xml (id: 3)
+    L2 Info : https://edt.univ-tlse3.fr/FSI/2017_2018/L2/L2_Info/g224636.xml (id: 13)
diff --git a/Documentation/usage/commands/reparse.rst b/Documentation/usage/commands/reparse.rst
new file mode 100644
index 0000000..78a54b7
--- /dev/null
+++ b/Documentation/usage/commands/reparse.rst
@@ -0,0 +1,11 @@
+===========
+``reparse``
+===========
+
+``reparse`` reparse tous les groupes dans la base de données.
+
+Utilisation
+===========
+.. code:: shell
+
+    $ ./manage.py reparse
diff --git a/Documentation/usage/commands/timetables.rst b/Documentation/usage/commands/timetables.rst
new file mode 100644
index 0000000..723b5aa
--- /dev/null
+++ b/Documentation/usage/commands/timetables.rst
@@ -0,0 +1,44 @@
+==============
+``timetables``
+==============
+
+``timetables`` met à jour les emplois du temps présents dans la base
+de données.
+
+Il est fortement recommandé d’exécuter régulièrement cette commande
+:ref:`à l’aide d’une tâche cron <ref-cron>`.
+
+Utilisation
+===========
+.. code:: shell
+
+    $ ./manage.py timetables [--all] [--force] [--week week] [--year year]
+
+Par défaut, ``timetables`` met à jour seulement la semaine courante ou
+à venir le week-end, et ne met pas à jour si la dernière mise à jour
+présente dans la base de données est plus récente que celle présente
+dans la source. Les différents paramètres permettent de contrôler ce
+comportement :
+
+``--all`` permet de mettre à jour toutes les semaines présentes dans
+la source.
+
+``--force`` force la mise à jour, même si la dernière mise à jour des
+emplois du temps présente dans la base de données est plus récente que
+celle présente dans la source.
+
+``--week`` permet de spécifier la semaine à mettre à jour.
+
+``--year`` permet de spécifier l’année à mettre à jour.
+
+Comportement
+============
+Pour chaque emploi du temps, ``timetables`` récupère la source,
+supprime les cours sur la période couverte par cette mise à jour,
+parse la source et insère les cours dans la base de données.
+
+Cette mise à jour est effectuée de manière transactionnelle : si la
+mise à jour d’une source échoue au milieu du processus, les données
+supprimées au début seront entièrement restaurées, les données
+rajoutées seront supprimées, et une erreur sera affichée. Cela
+n’affecte pas la mise à jour des autres emplois du temps.
diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst
new file mode 100644
index 0000000..2455996
--- /dev/null
+++ b/Documentation/usage/installation.rst
@@ -0,0 +1,285 @@
+===============================
+Installation de celcatsanitizer
+===============================
+
+Dépendances
+===========
+celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques
+suivantes :
+
+ - `Django 2.0`_
+ - requests_, pour récupérer les emplois du temps en HTTP(S)
+ - BeautifulSoup4_, pour parser les emplois du temps en XML
+ - icalendar_, pour générer des fichiers ICS_.
+
+*A priori*, il est possible d’utiliser n’importe quel SGBD supporté
+par Django avec celcatsanitizer. Cependant, l’utilisation de
+PostgreSQL_ est fortement recommandée. Dans ce cas, vous aurez besoin
+d’installer le module psycopg2_.
+
+Pour l’instant, l’installation doit passer par git_.
+
+.. _Django 2.0: https://www.djangoproject.com/
+.. _requests: http://docs.python-requests.org/en/master/
+.. _BeautifulSoup4:
+  https://www.crummy.com/software/BeautifulSoup/bs4/doc/
+.. _icalendar: https://icalendar.readthedocs.io/en/latest/
+.. _ICS: https://fr.wikipedia.org/wiki/ICalendar
+.. _PostgreSQL: https://www.postgresql.org/
+.. _psycopg2: http://initd.org/psycopg/docs/install.html
+.. _git: https://git-scm.com/
+
+Notes sur Django
+----------------
+celcatsanitizer utilise des versions assez récentes de Django,
+notamment en ce qui concerne son ORM. Le passage de Django 1.10 à
+Django 1.11 s’est fait pour utiliser l’annotation ``ExtractWeek``, le
+passage de Django 1.11 à Django 2.0 pour utiliser l’attribut
+``distinct`` de l’aggrégat ``ArrayAgg``.
+
+celcatsanitizer passera à Django 2.1 lorsqu’il sortira pour utiliser
+l’annotation ``TruncWeek``, pour l’instant implémenté avec une requête
+SQL brute. Cette fonctionnalité ne sera nécessaire que pour les
+utilisateurs de PostgreSQL.
+
+Installation
+============
+Création de l’environnement virtuel
+-----------------------------------
+Cette étape est optionnelle, mais est tout de même fortement
+recommandée.
+
+Placez-vous dans le répertoire souhaité, installez l’environnement
+virtuel, puis activez-le :
+
+.. code:: shell
+
+    $ virtualenv -p python3 celcatsanitizer
+    $ cd celcatsanitizer
+    $ source bin/activate
+
+Il est possible que votre version de pip soit ancienne. Si vous le
+souhaitez, mettez-le à jour :
+
+.. code:: shell
+
+    $ pip install -U pip
+
+Installation des dépendances
+----------------------------
+Vous pouvez demander à ``pip`` d’installer les dépendances à partir du
+fichier ``requirements.txt`` présent dans le dépôt :
+
+.. code:: shell
+
+    $ pip install -r requirements.txt
+
+Cette commande installera aussi ``psycopg2-binary`` et ``gunicorn``.
+
+Il est aussi possible d’installer les dépendances à la main :
+
+.. code:: shell
+
+    $ pip install django beautifulsoup4 icalendar requests
+
+Si vous utilisez PostgreSQL, vous devez installer le module
+psycopg2 :
+
+.. code:: shell
+
+    $ pip install psycopg2-binary
+
+Si vous êtes en production, il est recommandé d’utiliser gunicorn_ si
+vous n’utilisez pas le serveur Apache. Installez-le de la même
+manière :
+
+.. code:: shell
+
+    $ pip install gunicorn
+
+Création du projet Django
+-------------------------
+
+.. code:: shell
+
+    $ django-admin startproject celcatsanitizer
+    $ cd celcatsanitizer
+
+Récupération des sources de celcatsanitizer
+-------------------------------------------
+
+.. code:: shell
+
+    $ git clone https://git.pa1ch.fr/alban/celcatsanitizer.git edt
+
+Pour la production, il est recommandé d’utiliser une version
+stable. Elles sont accessibles à travers les tags git.
+
+Configuration de Django
+=======================
+Avant de pouvoir lancer celcatsanitizer, vous allez devoir modifier
+quelques fichiers.
+
+``settings.py``
+---------------
+Dans le fichier ``celcatsanitizer/settings.py``, vous devrez renseigner
+plusieurs informations.
+
+Configuration des administrateurs
+`````````````````````````````````
+Vous pouvez retrouver la documentation de la variable ``ADMIN`` `sur le
+site de Django`__.
+
+Cette variable est **obligatoire**.
+
+__ https://docs.djangoproject.com/fr/2.0/ref/settings/#admins
+
+Configuration de la base de données
+```````````````````````````````````
+Vous pouvez retrouver la documentation relative à la configuration de
+la base de données `sur le site de Django`__.
+
+Cette étape est **obligatoire**.
+
+__ https://docs.djangoproject.com/fr/2.0/ref/settings/#databases
+
+Configuration du mode de Django
+```````````````````````````````
+Si jamais vous utilisez Django en production, vous **devez
+impérativement** mettre la valeur de la variable ``DEBUG`` à
+``False``.
+
+Ajout de celcatsanitizer à la liste des applications Django
+```````````````````````````````````````````````````````````
+Ajoutez la chaîne de caractère ``edt`` à la liste ``INSTALLED_APPS``.
+
+Cette étape est **obligatoire**.
+
+.. _ref-flatpages:
+
+Activation des flatpages
+````````````````````````
+celcatsanitizer se sert des flatpages pour rendre les pages "contact"
+et "à propos". Vous pouvez retrouver le guide d’installation `sur le
+site de Django`__. Effectuez uniquement les deux premières étapes,
+celcatsanitizer enregistre déjà une route pour les pages statiques, et
+la commande de l’étape 4 sera effectuée plus loin.
+
+Cette étape est **obligatoire**.
+
+__
+  https://docs.djangoproject.com/fr/2.0/ref/contrib/flatpages/#installation
+
+Gestion des fichiers statiques
+``````````````````````````````
+Si vous êtes en production, vous devez renseigner l’emplacement de
+vos fichiers statiques dans la variable ``STATIC_ROOT`` de la
+configuration de Django (vous pouvez retrouver la documentation
+correspondante sur le site de Django).
+
+Cette étape est **obligatoire en production**, mais inutile en
+déboguage.
+
+Ajout du processeur de contexte de celcatsanitizer
+``````````````````````````````````````````````````
+Rajoutez la chaîne de caractères ``edt.views.ctx_processor`` à la
+liste ``context_processors`` dans la variable ``TEMPLATES``.
+
+Cette étape est **fortement recommandée**.
+
+Configuration de l’internationalisation
+```````````````````````````````````````
+Vous pouvez retrouver la documentation de l’internationalisation `sur
+le site de Django`__.
+
+Ce paramètre est **optionnel**.
+
+__ https://docs.djangoproject.com/fr/2.0/topics/i18n/
+
+``urls.py``
+-----------
+Dans le fichier ``celcatsanitizer/urls.py``, importez la fonction
+``django.conf.urls.include`` si elle ne l’est pas déjà, et rajouter
+``url(r'^', include("edt.urls"))`` à la *fin* de la liste
+``urlspatterns``.
+
+Cette étape est **obligatoire**.
+
+Derniers préparatifs
+====================
+Génération de la base de données
+--------------------------------
+Générez les migrations de Django et de celcatsanitizer, puis
+appliquez-les :
+
+.. code:: shell
+
+    $ ./manage.py makemigrations edt
+    $ ./manage.py migrate
+
+Collection des fichiers statiques
+---------------------------------
+Si vous êtes en production, il faut regrouper les fichiers
+statiques. Pour ce faire, exécutez la commande suivante :
+
+.. code:: shell
+
+    $ ./manage.py collectstatic
+
+Cette étape est **obligatoire** en production, mais inutile en
+déboguage.
+
+Création d’un super-utilisateur
+-------------------------------
+Pour pouvoir accéder à l’interface d’administration, il est important
+de créer un super-utilisateur. Pour cela, exécutez la commande
+suivante :
+
+.. code:: shell
+
+    $ ./manage.py createsuperuser
+
+Répondez ensuite aux questions posées.
+
+Cette étape est **fortement recommandée**.
+
+.. _ref-cron:
+
+Cron
+----
+Pour mettre à jour les emplois du temps de manière régulière, il faut
+rajouter :doc:`la commande de mise à jour <commands/timetables>` dans
+une tâche cron.
+
+Lancement
+=========
+En mode de déboguage
+--------------------
+Exécutez tout simplement la commande suivante :
+
+.. code:: shell
+
+    $ ./manage.py runserver
+
+En production
+-------------
+Le serveur intégré à Django n’est pas adapté pour un usage en
+production. Il vaut mieux utiliser Apache avec mod_wsgi, ou avec un
+serveur gunicorn_ derrière nginx_.
+
+.. _gunicorn: https://gunicorn.org/
+.. _nginx: https://nginx.org/en/
+
+Ajout des pages statiques
+=========================
+:ref:`Comme indiqué plus haut <ref-flatpages>`, celcatsanitizer fait
+appel aux flatpages de Django.
+
+À l’aide de l’interface d’administration de Django (si votre instance
+se trouve à l’adresse ``example.com``, vous pourrez y accéder à
+l’adresse ``example.com/admin``), dans la section "pages statiques",
+rajoutez les pages ``/a-propos/`` et ``/contact/``.
+
+Si vous êtes en production, changez le site de base (``example.com``)
+par le site sur lequel se trouvera votre instance de celcatsanitizer,
+trouvable dans la section "sites".
diff --git a/Documentation/usage/versions.rst b/Documentation/usage/versions.rst
new file mode 100644
index 0000000..d6b8f00
--- /dev/null
+++ b/Documentation/usage/versions.rst
@@ -0,0 +1,35 @@
+================
+Notes de version
+================
+
+Version 0.13
+============
+Changements externes
+--------------------
+ - Ajout de l’emploi du temps des salles
+ - Ajout d’une fonctionnalité permettant de connaître les salles
+   disponibles
+ - Améliorations de la navigabilité du site
+
+   - Ajout de liens pour revenir en arrière sur le site
+   - Ajout de liens pour parcourir les semaines de l’emploi du temps
+
+ - Les groupes qui n’ont plus de cours du tout ne sont plus affichés
+ - Ajout d’une page contenant la liste complète des groupes
+ - Ajout d’une page contenant la liste complète des semaines de cours
+   pour les groupes et les salles
+ - Ajout d’un texte de description sur la page des ICS
+ - Création de la documentation
+
+Changements internes
+--------------------
+ - Passage à Django 2.0
+
+   - Utilisation des routes ``path()`` au lieu de ``url()``
+
+ - Création d’une table ``Source`` pour stocker la source des emplois
+   du temps. Cela permet d’éviter de récupérer plusieurs fois le même
+   fichier et d’éviter les doublons sur les emplois du temps des
+   salles.
+ - Ajout de la commande :doc:`reparse <commands/reparse>`
+ - Meilleure abstraction des templates, notamment de ``index.html``