From 9987d47ec8c74d649de2a7d09ef62beb885949d9 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 27 Jan 2019 21:47:39 +0100 Subject: Documentation: ajout d’une doc sur l’API REST Signed-off-by: Alban Gruin --- Documentation/usage/installation.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'Documentation/usage/installation.rst') diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 4dde4f4..75e0be1 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -8,6 +8,7 @@ celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - `Django 2.0`_ + - `Django REST Framework`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. @@ -25,6 +26,7 @@ d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. .. _Django 2.0: https://www.djangoproject.com/ +.. _Django REST Framework: https://www.django-rest-framework.org/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ @@ -155,6 +157,23 @@ Si jamais vous utilisez Django en production, vous **devez impérativement** mettre la valeur de la variable ``DEBUG`` à ``False``. +Configuration de Django REST Framework +`````````````````````````````````````` +Ajoutez la chaîne de caractère ``rest_framework`` à la liste +``INSTALLED_APPS``. + +Libre à vous de configurer DRF de la manière dont vous le souhaitez. +`Les différents paramètres sont accessibles ici`__. Les plus +intéressants sont ``DEFAULT_PERMISSION_CLASSES``, +``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et +``PAGE_SIZE``. + +__ https://www.django-rest-framework.org/api-guide/settings/ + +Cette étape est **obligatoire**, mais deviendra optionnelle dans le +futur. Dans le cas ou vous ne souhaiterez pas la faire, l’API REST ne +sera pas activée. + Ajout de celcatsanitizer à la liste des applications Django ``````````````````````````````````````````````````````````` Ajoutez la chaîne de caractère ``edt`` à la liste ``INSTALLED_APPS``. -- cgit v1.2.1 From c2a2f5aac817d4255c30c447808ec08faecda036 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 9 Jun 2019 19:41:38 +0200 Subject: api: ajout d’un paramètre pour activer ou non l’API L’API devient optionnelle, et un paramètre, CS_ENABLE_API, est rajouté pour sélectionner son état (activé ou non). Par défaut, il est désactivé. La documentation est mise à jour pour refléter ces changements. Signed-off-by: Alban Gruin --- Documentation/usage/installation.rst | 58 ++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 19 deletions(-) (limited to 'Documentation/usage/installation.rst') diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 75e0be1..92b3c5d 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -8,11 +8,14 @@ celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - `Django 2.0`_ - - `Django REST Framework`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. +Une dépendance est optionnelle : + + - `Django REST Framework`_, pour l’:doc:`API REST `. + celcatsanitizer requiert Python 3.4 au minimum, et marche avec les versions 3.5 et 3.6. Les versions antérieures de Python 3 n’ont pas étés testées, et les versions supérieures devraient fonctionner sans @@ -26,13 +29,13 @@ d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. .. _Django 2.0: https://www.djangoproject.com/ -.. _Django REST Framework: https://www.django-rest-framework.org/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ .. _LXML: https://lxml.de/ .. _icalendar: https://icalendar.readthedocs.io/en/latest/ .. _ICS: https://fr.wikipedia.org/wiki/ICalendar +.. _Django REST Framework: https://www.django-rest-framework.org/ .. _PostgreSQL: https://www.postgresql.org/ .. _psycopg2: http://initd.org/psycopg/docs/install.html .. _git: https://git-scm.com/ @@ -97,6 +100,13 @@ psycopg2 : $ pip install psycopg2-binary +Si vous souhaitez activer l’API REST, vous devez installer le module +Django Rest Framework : + +.. code:: shell + + $ pip install djangorestframework + 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 : @@ -157,23 +167,6 @@ Si jamais vous utilisez Django en production, vous **devez impérativement** mettre la valeur de la variable ``DEBUG`` à ``False``. -Configuration de Django REST Framework -`````````````````````````````````````` -Ajoutez la chaîne de caractère ``rest_framework`` à la liste -``INSTALLED_APPS``. - -Libre à vous de configurer DRF de la manière dont vous le souhaitez. -`Les différents paramètres sont accessibles ici`__. Les plus -intéressants sont ``DEFAULT_PERMISSION_CLASSES``, -``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et -``PAGE_SIZE``. - -__ https://www.django-rest-framework.org/api-guide/settings/ - -Cette étape est **obligatoire**, mais deviendra optionnelle dans le -futur. Dans le cas ou vous ne souhaiterez pas la faire, l’API REST ne -sera pas activée. - Ajout de celcatsanitizer à la liste des applications Django ``````````````````````````````````````````````````````````` Ajoutez la chaîne de caractère ``edt`` à la liste ``INSTALLED_APPS``. @@ -251,6 +244,33 @@ Ce paramètre est **optionnel**. __ https://docs.djangoproject.com/fr/2.0/topics/i18n/ +Activation de l’API REST et configuration de Django Rest Framework +`````````````````````````````````````````````````````````````````` +L’API REST permet à des outils tiers d’accéder facilement aux données +gérées par celcatsanitizer. Elle est optionnelle, et est basée sur +Django Rest Framework. :doc:`Plus d’informations sur la page de l’API +REST `. + +Si vous souhaitez l’activer, vous devez d’abord avoir installé Django +REST Framework, puis mettre la variable ``CS_ENABLE_API`` à ``True``. + +.. code:: Python + + CS_ENABLE_API = True + +Ajoutez ensuite la chaîne de caractère ``rest_framework`` à la liste +``INSTALLED_APPS``. + +Libre à vous de configurer DRF de la manière dont vous le souhaitez. +`Les différents paramètres sont accessibles ici`__. Les plus +intéressants sont ``DEFAULT_PERMISSION_CLASSES``, +``DEFAULT_RENDERER_CLASSES``, ``DEFAULT_PAGINATION_CLASS`` et +``PAGE_SIZE``. + +__ https://www.django-rest-framework.org/api-guide/settings/ + +Cette étape est **optionnelle**. + ``urls.py`` ----------- Dans le fichier ``celcatsanitizer/urls.py``, importez la fonction -- cgit v1.2.1 From a6eaecf48f63c37cf851386a45cd4b25ac3ed1e0 Mon Sep 17 00:00:00 2001 From: Alban Gruin Date: Sun, 1 Sep 2019 18:51:10 +0200 Subject: doc: mise à jour de la doc pour la future version 0.16 Signed-off-by: Alban Gruin --- Documentation/usage/installation.rst | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) (limited to 'Documentation/usage/installation.rst') diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst index 92b3c5d..b86b257 100644 --- a/Documentation/usage/installation.rst +++ b/Documentation/usage/installation.rst @@ -7,7 +7,7 @@ Dépendances celcatsanitizer est écrit en Python 3. Il dépend des bibliothèques suivantes : - - `Django 2.0`_ + - `Django 2.2`_ - requests_, pour récupérer les emplois du temps en HTTP(S) - BeautifulSoup4_ et LXML_, pour parser les emplois du temps en XML - icalendar_, pour générer des fichiers ICS_. @@ -16,10 +16,9 @@ Une dépendance est optionnelle : - `Django REST Framework`_, pour l’:doc:`API REST `. -celcatsanitizer requiert Python 3.4 au minimum, et marche avec les -versions 3.5 et 3.6. Les versions antérieures de Python 3 n’ont pas -étés testées, et les versions supérieures devraient fonctionner sans -problèmes. +celcatsanitizer requiert Python 3.6 au minimum. Les versions +supérieures devraient fonctionner sans problèmes, mais pas les +versions antérieures. *A priori*, il est possible d’utiliser n’importe quel SGBD supporté par Django avec celcatsanitizer. Cependant, l’utilisation de @@ -28,7 +27,7 @@ d’installer le module psycopg2_. Pour l’instant, l’installation doit passer par git_. -.. _Django 2.0: https://www.djangoproject.com/ +.. _Django 2.2: https://www.djangoproject.com/ .. _requests: http://docs.python-requests.org/en/master/ .. _BeautifulSoup4: https://www.crummy.com/software/BeautifulSoup/bs4/doc/ @@ -46,12 +45,9 @@ 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. +``distinct`` de l’aggrégat ``ArrayAgg``. Il utilise l’aggrégat +``TruncWeek`` apparu dans Django 2.1, et se base officiellement sur +Django 2.2 pour bénéficier du support à long terme. Installation ============ @@ -191,7 +187,7 @@ __ Sélection du parseur ```````````````````` celcatsanitizer dispose d’un système de parseurs modulaires depuis la -:ref:`version 0.14 `, et embarque par défaut deux +:ref:`version 0.14 `, et embarque par défaut trois parseurs : - ``edt.management.parsers.ups2017``, pour le format utilisé par @@ -201,6 +197,9 @@ parseurs : - ``edt.management.parsers.ups2018``, pour le format utilisé par l’Université Paul Sabatier en 2018. Ce parseur utilise LXML_ et exploite l’IO asynchrone de Python. + - ``edt.management.parsers.ups2019``, pour le format utilisé par + l’Université Paul Sabatier en 2019. Ce parseur utilise le module + JSON standard. Pour spécifier le parseur à utiliser, il faut rajouter une variable ``CS_PARSER``, contenant le parseur à utiliser sous forme de chaîne de -- cgit v1.2.1