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/installation.rst | 267 +++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 Documentation/usage/installation.rst (limited to 'Documentation/usage/installation.rst') 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". -- 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/installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/usage/installation.rst') 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 ========= -- 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/installation.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'Documentation/usage/installation.rst') 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/installation.rst') 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