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/usage/commands.rst | 30 ++++ Documentation/usage/installation.rst | 267 +++++++++++++++++++++++++++++++++++ Documentation/usage/versions.rst | 35 +++++ 3 files changed, 332 insertions(+) create mode 100644 Documentation/usage/commands.rst create mode 100644 Documentation/usage/installation.rst create mode 100644 Documentation/usage/versions.rst (limited to 'Documentation/usage') diff --git a/Documentation/usage/commands.rst b/Documentation/usage/commands.rst new file mode 100644 index 0000000..5dede31 --- /dev/null +++ b/Documentation/usage/commands.rst @@ -0,0 +1,30 @@ +================================================ +Manuel des commandes intégrées à celcatsanitizer +================================================ + +``cleancourses`` +================ +**ATTENTION : cette commande est irréversible.** + +Cette commande permet d’effacr tous les cours présents dans la base. + +``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. + +.. _ref-reparse: + +``reparse`` +=========== +Reparse les groupes dans la base de données. + +.. _ref-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 `. diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst new file mode 100644 index 0000000..7290df1 --- /dev/null +++ b/Documentation/usage/installation.rst @@ -0,0 +1,267 @@ +=============================== +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 +---------------------------- + +.. code:: shell + + $ pip install django beautifulsoup4 icalendar requests + +Si vous utilisez PostgreSQL, vous devez installer le module +psycopg2 : + +.. code:: shell + + $ pip install psycopg2 + +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). Puis, exécutez la commande +suivante : + +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 :ref:`la commande de mise à jour ` 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/ + +Ajout des pages statiques +========================= +:ref:`Comme indiqué plus haut `, 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..0f354bc --- /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 :ref:`reparse ` + - Meilleure abstraction des templates, notamment de ``index.html`` -- cgit v1.2.1 From b6e146c48fa3c25e419bc0458e423cbef3dee133 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 22 Apr 2018 12:07:56 +0200 Subject: doc: documentation des commandes administratives --- Documentation/usage/commands.rst | 30 ----------------- Documentation/usage/commands/cleancourses.rst | 21 ++++++++++++ Documentation/usage/commands/listtimetables.rst | 26 +++++++++++++++ Documentation/usage/commands/reparse.rst | 11 +++++++ Documentation/usage/commands/timetables.rst | 44 +++++++++++++++++++++++++ Documentation/usage/installation.rst | 4 +-- Documentation/usage/versions.rst | 2 +- 7 files changed, 105 insertions(+), 33 deletions(-) delete mode 100644 Documentation/usage/commands.rst create mode 100644 Documentation/usage/commands/cleancourses.rst create mode 100644 Documentation/usage/commands/listtimetables.rst create mode 100644 Documentation/usage/commands/reparse.rst create mode 100644 Documentation/usage/commands/timetables.rst (limited to 'Documentation/usage') diff --git a/Documentation/usage/commands.rst b/Documentation/usage/commands.rst deleted file mode 100644 index 5dede31..0000000 --- a/Documentation/usage/commands.rst +++ /dev/null @@ -1,30 +0,0 @@ -================================================ -Manuel des commandes intégrées à celcatsanitizer -================================================ - -``cleancourses`` -================ -**ATTENTION : cette commande est irréversible.** - -Cette commande permet d’effacr tous les cours présents dans la base. - -``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. - -.. _ref-reparse: - -``reparse`` -=========== -Reparse les groupes dans la base de données. - -.. _ref-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 `. diff --git a/Documentation/usage/commands/cleancourses.rst b/Documentation/usage/commands/cleancourses.rst new file mode 100644 index 0000000..4ca60b0 --- /dev/null +++ b/Documentation/usage/commands/cleancourses.rst @@ -0,0 +1,21 @@ +================ +``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 `. + +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 index 7290df1..e3ae9e9 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -231,8 +231,8 @@ Cette étape est **fortement recommandée**. Cron ---- Pour mettre à jour les emplois du temps de manière régulière, il faut -rajouter :ref:`la commande de mise à jour ` dans une -tâche cron. +rajouter :doc:`la commande de mise à jour ` dans +une tâche cron. Lancement ========= diff --git a/Documentation/usage/versions.rst b/Documentation/usage/versions.rst index 0f354bc..d6b8f00 100644 --- a/Documentation/usage/versions.rst +++ b/Documentation/usage/versions.rst @@ -31,5 +31,5 @@ Changements internes 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 :ref:`reparse ` + - Ajout de la commande :doc:`reparse ` - Meilleure abstraction des templates, notamment de ``index.html`` -- cgit v1.2.1 From ea38d01d76f695d529284c841fe9ba7f441bad1b Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Mon, 23 Apr 2018 12:03:00 +0200 Subject: doc: corrections de grammaire --- Documentation/usage/commands/cleancourses.rst | 1 - Documentation/usage/installation.rst | 3 +-- 2 files changed, 1 insertion(+), 3 deletions(-) (limited to 'Documentation/usage') diff --git a/Documentation/usage/commands/cleancourses.rst b/Documentation/usage/commands/cleancourses.rst index 4ca60b0..6e4f152 100644 --- a/Documentation/usage/commands/cleancourses.rst +++ b/Documentation/usage/commands/cleancourses.rst @@ -8,7 +8,6 @@ seule source. **ATTENTION : cette commande est irréversible.** - Utilisation =========== diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index e3ae9e9..795d4a9 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -157,8 +157,7 @@ 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). Puis, exécutez la commande -suivante : +correspondante sur le site de Django). Cette étape est **obligatoire en production**, mais inutile en déboguage. -- cgit v1.2.1 From 8a533b6f86dc3315c3359f9e0df7af360b698a48 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Mon, 23 Apr 2018 16:22:50 +0200 Subject: doc: ajout de la méthode d’installation avec requirements.txt --- Documentation/usage/installation.rst | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) (limited to 'Documentation/usage') diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 795d4a9..2455996 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -67,17 +67,35 @@ souhaitez, mettez-le à jour : 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 : +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 psycopg2 + $ pip install gunicorn Création du projet Django ------------------------- @@ -247,9 +265,10 @@ 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. +serveur gunicorn_ derrière nginx_. .. _gunicorn: https://gunicorn.org/ +.. _nginx: https://nginx.org/en/ Ajout des pages statiques ========================= -- cgit v1.2.1