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