update docs

docs/guide-admin/index.rst

+Guide de l'administrateur
+=========================
+
+.. toctree::
+
+  gestion-utilisateurs

docs/guide-developpeur/index.rst

+Guide du développeur
+====================
+
+.. toctree::
+  :maxdepth: 2
+
+  introduction
+  installation
+  documenter

docs/installation.rst → docs/guide-developpeur/installation.rst

@@ -2,66 +2,108 @@
 Installation
 ============
 
-Cette page vous indique étape par étape comme installer l'environnement de développement du backend du site. À la fin de ce processus, vous aurez un backend local fonctionnel !
+Le site d'OSER est décomposée en deux parties : le backend et le frontend qui communiquent essentiellement via une API REST. En conséquence, il y a **deux serveurs de développement** à installer : le serveur backend et le serveur frontend.
+
+Cette page vous indique étape par étape comment installer chacun de ces serveurs en local. Cela vous permet de faire tourner le site sur votre propre ordinateur afin d'y apporter des modifications.
 
 Prérequis
 =========
 
-Vous aurez besoin de `Git <https://git-scm.com>`_ pour cloner le dépôt.
+Git
+---
+
+Vous aurez besoin de `Git <https://git-scm.com>`_ pour cloner le dépôt. Une connaissance basique de ce système de gestion de version est requise. Référez-vous à des tutoriels (par exemple `celui-ci <https://try.github.io/levels/1/challenges/1>`_) si besoin. :)
+
+Backend
+-------
+
+Python et virtualenv
+********************
 
 Le backend du site repose sur Django et donc Python. Munissez-vous de `Python 3.5+ <https://www.python.org/downloads/>`_ et de `virtualenv <https://pypi.python.org/pypi/virtualenv>`_ si ce n'est pas encore fait. Vous pouvez aussi consulter la page :doc:`ressources-apprentissage/dev-python` pour plus d'informations sur l'installation et l'utilisation de ``virtualenv``.
 
+Django et le Django REST Framework
+**********************************
+
+Une connaissance minimale de Django est requise, c'est pourquoi je vous recommande fortement de suivre quelques tutoriels, par exemple `celui d'OpenClassrooms <https://openclassrooms.com/courses/introduction-au-framework-django>`_. Vous pouvez passer rapidement sur les templates, car comme précisé en introduction cette partie de Django n'est pas utilisée ici.
+
+Enfin, la gestion de l'API REST suppose une connaissance minimale du `Django REST Framework (DRF) <http://www.django-rest-framework.org>`_, une surcouche de Django qui permet d'écrire facilement et efficacement une API REST. Jetez un œil à la page `Tutorials and resources <http://www.django-rest-framework.org/topics/tutorials-and-resources/>`_ du DRF pour bien démarrer.
+
+Frontend
+--------
+
+.. note:: En construction
+
+Serveur backend
+================
+
+Nous allons voir ici comment installer l'environnement de développement backend du site. Le backend concerne, rappelons-le, tout ce qui ne concerne pas l'interface utilisateur : bases de données, tâches de fond, services… À la fin de ce processus, vous aurez un serveur backend local fonctionnel !
+
 Installation des dépendances
-============================
+----------------------------
 
-Tout d'abord, clonez le dépôt sur votre ordinateur :
+Tout d'abord, clonez le dépôt du backend sur votre ordinateur :
 ::
   $ git clone https://github.com/oser-cs/oser-backend.git
   $ cd oser-backend
 
-Créez ensuite un environnement virtuel (ici appelé ``env``) puis activez-le :
+Créez ensuite un environnement virtuel appelé ``env`` puis activez-le :
 ::
-  oser-backend $ virtualenv env -p python 3
+  oser-backend $ virtualenv env
   oser-backend $ source env/bin/activate
 
-Installez les dépendances Python en utilisant ``pip`` :
+Installez les dépendances Python du back en utilisant ``pip`` :
 ::
   (env) oser-backend $ pip install -r requirements.txt
 
-Configuration de la base de données
-===================================
-
-Tout d'abord, créez puis exécutez les migrations Django :
+Vous pouvez ensuite vous placer dans le dossier source, d'où vous effectuerez la majorité de votre travail :
 ::
   (env) oser-backend $ cd oser_backend
-  (env) oser_backend $ python manage.py makemigrations
-  (env) oser_backend $ python manage.py migrate
 
-Lancez les tests pour vous assurer que tout fonctionne comme prévu :
+.. note:: Les aperçus shell ci-après ne feront plus apparaître le préfixe de la ligne de commande. Sauf indication contraire, on supposera que le dossier courant est ``oser-backend/oser_backend`` (là où se situe le fichier ``manage.py``) et que l'environnement virtuel est, le cas échéant, activé.
+
+Configuration de la base de données
+-----------------------------------
+
+Pour tourner, le back a besoin d'une **base de données**. À ce stade, vous n'en avez pas encore. Django permet de générer la base de données et son schéma grâce aux **migrations** : il analyse la base de données actuelle et détermine automatiquement les opérations à effectuer pour la rendre opérationnelle et synchronisée avec le code source.
+
+Du coup, creéz puis exécutez les migrations Django :
 ::
-  (env) oser_backend $ python manage.py test
+  $ python manage.py makemigrations
+  $ python manage.py migrate
+
+Exécution des tests
+-------------------
 
-Optionnel : vous pouvez peupler la BDD de développement avec de "fausses données" en utilisant la commande ``populatedb`` :
+Le serveur backend dispose d'une batterie de tests qui permettent de s'assurer que la majorité des fonctionnalités est opérationnelle. Lancez les tests pour vous assurer que tout fonctionne comme prévu :
 ::
-  (env) oser_backend $ python manage.py populatedb
+  $ python manage.py test
 
-Démarrage du site en mode développement
-=======================================
+Population de la base de données (optionnel)
+--------------------------------------------
 
-Vous en fait avez besoin de démarrer deux serveurs : le serveur backend avec Django et le serveur frontend avec npm (le second communicant avec le premier via l'API).
+Vous pouvez peupler la base de données avec des données factices. Cette étape est recommandée si vous prévoyez d'accéder au frontend (sinon, le site aura l'air bien vide…).
 
-Démarrez le serveur local Django avec la commande ``runserver`` :
+Pour cela, utilisez la commande ``populatedb`` :
 ::
-  (env) oser_backend $ python manage.py runserver
+  $ python manage.py populatedb
+
+.. todo::
+  Guide d'utilisation et de maintenance de ``populatedb``.
 
-Si vous vous rendez à l'adresse `http://localhost:8000/api/ <http://localhost:8000/api/>`_, vous devriez arriver à la racine de l'API comme ci-dessous. Si c'est le cas, le serveur Django est fonctionnel ! 👍
+Démarrage du site en mode développement
+---------------------------------------
 
-.. image:: media/api_home.png
+Une fois tout ceci fait, vous pouvez démarrer le serveur local Django avec la commande ``runserver`` :
+::
+  (env) oser_backend $ python manage.py runserver
 
+Si vous vous rendez à l'adresse `http://localhost:8000/ <http://localhost:8000/>`_, vous devriez voir apparaître la documentation de l'API. Si c'est le cas, le serveur Django est fonctionnel ! 👍
 
+.. image:: /media/api-docs.png
 
 Détail des dépendances
-======================
+----------------------
 
 .. _Django : https://www.djangoproject.com
 .. _release news: https://www.djangoproject.com/weblog/2017/dec/02/django-20-released/)
@@ -81,14 +123,12 @@ Le site d'OSER utilise Django en version 2.0.
 Django REST Framework
 *********************
 
-Le `Django REST Framework`_ (DRF) permet d'écrire facilement des API REST avec Django.
-
-Le site d'OSER utilise le DRF en version 3.7.3. Cette version est entièrement compatible avec Django 2.0.
+Le `Django REST Framework`_ (DRF) permet d'écrire facilement des API REST avec Django. Le site d'OSER utilise le DRF en version 3.7.3. Cette version est entièrement compatible avec Django 2.0.
 
 DRY Rest Permissions
 ********************
 
-`DRY Rest Permissions`_ est utilisé pour définir les permissions directement sur les modèles Django.
+`DRY REST Permissions`_ est utilisé pour définir les permissions de l'API directement sur les modèles Django.
 
 FactoryBoy
 **********

docs/guide-developpeur/introduction.rst

+============
+Introduction
+============
+
+Éléments d'historique
+=====================
+
+Septembre 2017
+  Reformation du secteur Geek, rassemblement de tuteurs intéressés.
+
+Octobre 2017
+  Début du développement du site web d'OSER.
+
+Octobre 2017 - Janvier 2018
+  Phase d'étude du besoin et de listing des fonctionnalités. Le résultat est un `Trello Geek <https://trello.com/oser_cs_geek>`_ bien fourni, toujours en évolution !
+
+Mi-janvier 2018
+  L'implémentation du site a sérieusement démarré. Les priorités : site vitrine et procédure d'inscription administrative des lycéens.
+
+Mi-février 2018
+  Le site vitrine est presque abouti.
+
+Choix techniques
+================
+
+Décomposition backend/frontend
+------------------------------
+
+Tout site internet repose sur une **stack technique** qui constitue l'ensemble des technos utilisées pour réaliser le site. Avec l'avènement des frameworks Javascript, cette stack est de plus en plus souvent décomposée en 2 aspects :
+
+- D'une part le *frontend* qui gère l'interface utilisateur (le rendu dans le navigateur)
+- D'autre part le *backend* qui gère le reste, c'est-à-dire essentiellement la base de données, les services, les tâches de fond, etc.
+
+Cette architecture est historiquement motivée par la démultiplication des supports et des environnements (web, mobile : iOS, Android, Windows Phone, natif…) qui n'influencent que l'interface utilisateur mais pas le modèle de données sous-jacent. Ce dernier a donc été extrait dans un modèle *backend as a service*. Les clients frontend multiples font des appels à un backend unique et donc plus facilement maintenable. Par ailleurs, un frontend dédié permet le plus souvent de réaliser des applications plus interactives.
+
+Le site d'OSER emploie cette décomposition. et dispose donc d'un **frontend Javascript/Angular4** et d'un **backend Python/Django** qui communiquent via une **API REST**.
+
+  *Une API REST ? Qu'est-ce que c'est que ça ?*
+
+Vaste sujet ! En essence, une API REST est **une interface de programmation** qui permet de **récupérer des ressources** d'un serveur de données via de **simples requêtes HTTP**. Les données envoyées ou reçues sont encodées selon le format standard **JSON**.
+
+L'intérêt des API REST est de faciliter **l'interopérabilité** et donc l'utilisation d'un **même serveur de données pour plusieurs clients**. On dispose aujourd'hui d'un backend Django qui sert un client Javascript, mais si OSER envisage un jour de développer une app mobile, celle-ci pourra réutiliser le backend développé pour le site en communiquant sur l'API REST. En résumé, voyez simplement l'API REST comme le langage commun qui permet à un client quelconque de communiquer avec le serveur backend.
+
+Technos employées
+-----------------
+
+Django et le Django REST Framework
+**********************************
+
+Le choix de **Django** pour le back repose sur l'hypothèse que si des tuteurs connaissent un langage de programmation, il y a de fortes chances que ce soit Python. Parmi les frameworks web Python, Django est probablement le plus complet et le plus mature. Le développement d'API est grandement facilité grâce au Django REST Framework. Enfin, les solutions d'hébergement Python se développent de plus en plus, le déploiement ne devrait donc pas poser trop de problèmes.
+
+**Django**
+
+Django est un framework complet qui permet de réaliser un site internet de bout en bout, de la gestion de la base de données à la génération des réponses HTTP en passant par la génération de contenu HTML. Django est structuré en trois grands concepts selon le modèle MVT : le Modèle (gestion de la BDD), la Vue (extraction et mise en forme de données) et le Template (génération de contenu HTML à partir des données de la Vue).
+
+Cependant, comme on l'a dit, **le backend du site ne gère pas l'interface utilisateur**. En conséquence, **la partie Template est complètement bypassée** (on ne l'utilise pas, mais elle reste fonctionnelle) et remplacée par l'API REST que le frontend peut utiliser pour récupérer des données.
+
+
+**Django REST Framework (DRF)**
+
+Il s'agit d'une bibliothèque qui repose sur Django et permet de développer une API REST en réutilisant les modèles Django. Cela en fait un outil progressif. Par ailleurs, le DRF offre de nombreux outils très intéressants comme la génération de documentation automatique ou l'API parcourable.
+
+Angular 4
+*********
+
+Côté front, **Angular** est également le framework Javascript le plus mature. La version 4 est la version actuelle. Il a aussi l'avantage d'imposer une certaine structure (autour de concepts comme les *NgModules*, les *Components* et autres *Services*…) et donc d'établir des conventions que tout le monde peut suivre. Enfin, il utilise TypeScript, une variante de Javascript qui permet d'écrire du Javascript typé (et facilite grandement la détection de bugs en amont, le déboggage de code Javascript n'étant jamais une partie de plaisir).
+
+Sources de documentation
+------------------------
+
+- `Django <https://docs.djangoproject.com/en/2.0/>`_
+- `Django REST Framework <http://www.django-rest-framework.org>`_
+- `Angular 4 <https://angular.io/docs>`_
+
+------
+
+  *Pourquoi ne pas avoir employé un CMS comme Wordpress ?*
+
+Tout d'abord, personne dans l'équipe ne connaissait Wordpress. Ensuite, dès le départ, nous savions que le site d'OSER allait être très interactif et *data-oriented*. Il nous a semblé qu'opter pour une solution front/back personnalisée, en utilisant des frameworks efficaces, stables et qui ne réinventent pas la roue, permettrait d'obtenir un site adapté aux besoins de l'association.

docs/index.rst

@@ -14,17 +14,17 @@ Cette documentation est destinée aux développeurs du site web d'OSER. Vous tro
 
 .. toctree::
   :maxdepth: 2
-  :caption: Guide de l'administrateur
 
-  gestion-utilisateurs
+  guide-admin/index
+
+.. toctree::
+  :maxdepth: 2
+
+  guide-developpeur/index
 
 .. toctree::
   :maxdepth: 2
-  :caption: Guide du développeur
 
-  introduction
-  installation
-  documenter
   ressources-apprentissage/index
 
 

docs/introduction.rst

-============
-Introduction
-============
-
-.. note:: 
-  En construction