Skip to content
Snippets Groups Projects
Commit 46125e53 authored by florimondmanca's avatar florimondmanca
Browse files

update docs, update README

parent bfe17ada
No related branches found
No related tags found
No related merge requests found
...@@ -23,24 +23,28 @@ De nombreuses informations sont également disponibles sur le [Wiki](https://git ...@@ -23,24 +23,28 @@ De nombreuses informations sont également disponibles sur le [Wiki](https://git
## Table des matières ## Table des matières
- [Dépendances](#dépendances)
- [Installation](#installation)
- [Documentation](#documentation) - [Documentation](#documentation)
- [Dépendances](#dépendances)
- [Contribuer](#contribuer) - [Contribuer](#contribuer)
- [À propos d'OSER](#À-propos-doser) - [À propos d'OSER](#À-propos-doser)
## Dépendances ## Documentation
:construction: Section en construction. La documentation complète du site est hébergée sur [ReadTheDocs](http://oser-website.readthedocs.io/fr/latest/).
La documentation de l'API est accessible à l'endpoint `/api/docs/`. Sur le serveur local, vous pouvez donc y accéder à l'URL [`http://localhost:8000/api/docs`](http://localhost:8000/api/docs). Vous pouvez aussi librement parcourir l'API à l'adresse [`http://localhost:8000/api/`](http://localhost:8000/api/).
![API Docs](media/api-docs.png)
#### Structure des données
> Lister ici les frameworks, packages et autres technos sur lesquelles le projet s'appuie. Pour chaque dépendance, indiquer : TODO
> - la version utilisée ;
> - pour quoi la dépendance est utilisée ;
> - comment l'installer (instructions ou lien vers une ressource externe).
### Backend ## Dépendances
#### Django :construction: Section en construction.
### Django
[Django](https://www.djangoproject.com) est un framework de développement web pour Python. [Django](https://www.djangoproject.com) est un framework de développement web pour Python.
...@@ -48,70 +52,21 @@ Le site d'OSER utilise Django en version 2.0. ...@@ -48,70 +52,21 @@ Le site d'OSER utilise Django en version 2.0.
> À l'heure actuelle, peu de tutoriels Django se basent sur la version 2.0, mais il y a en fait très peu de changements non-rétro-compatibles par rapport à la version 1.11, et aucun changement n'est réellement critique. Les améliorations apportées par la version 2.0 sont intéressantes, on peut notamment citer le système d'écriture des URLs qui est grandement simplifié. Pour plus d'infos, lire la [release news](https://www.djangoproject.com/weblog/2017/dec/02/django-20-released/) associée. > À l'heure actuelle, peu de tutoriels Django se basent sur la version 2.0, mais il y a en fait très peu de changements non-rétro-compatibles par rapport à la version 1.11, et aucun changement n'est réellement critique. Les améliorations apportées par la version 2.0 sont intéressantes, on peut notamment citer le système d'écriture des URLs qui est grandement simplifié. Pour plus d'infos, lire la [release news](https://www.djangoproject.com/weblog/2017/dec/02/django-20-released/) associée.
#### Django REST Framework ### Django REST Framework
Le [Django REST Framework](http://www.django-rest-framework.org) (DRF) permet d'écrire facilement des API REST avec Django. Le [Django REST Framework](http://www.django-rest-framework.org) (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 site d'OSER utilise le DRF en version 3.7.3. Cette version est entièrement compatible avec Django 2.0.
#### DRY Rest Permissions ### React
[DRY Rest Permissions](https://github.com/dbkaplan/dry-rest-permissions) est utilisé pour définir les permissions directement sur les modèles Django.
#### FactoryBoy
[FactoryBoy](http://factoryboy.readthedocs.io/en/latest/index.html) est utilisé pour faciliter la création d'objets de test en définissant des usines (*factories*) directement à partir des modèles Django. Les usines sont définies dans `oser_cs/tests/factory.py`.
## Documentation
La documentation du site est hébergée sur [ReadTheDocs](http://oser-website.readthedocs.io/fr/latest/).
### Backend
#### Structure des données
TODO TODO
#### Documentation de l'API
Elle est accessible à l'endpoint `/api/docs/`. Sur le serveur local, vous pouvez donc y accéder à l'URL [`http://localhost:8000/api/docs`](http://localhost:8000/api/docs).
![API Docs](media/api-docs.png)
## Contribuer ## Contribuer
Le backlog est recensé sur le [Trello OSER_Geek](https://trello.com/b/bYlju4gE/site-internet-backlog). Le backlog est recensé sur le [Trello OSER_Geek](https://trello.com/b/bYlju4gE/site-internet-backlog).
:construction: Section en construction. Consultez le guide du développeur de la [documentation](http://localhost:8000/index.html) pour plus d'informations sur le développement du site.
### Pratiques de test
- Dès que vous corrigez un bug, pensez à écrire un test de non-régression (qui permettra de s'assurer que le bug n'arrive plus).
- Tout élément de *business logic* doit être testé par un test fonctionnel.
#### Test de l'API
- Les tests de l'API sont définis dans le package `tests/test_api`.
- Tous les endpoints d'une ressource doivent être testés par un test fonctionnel qui envoie la requête et s'assure que le `status_code` est celui attendu.
- Les permissions d'un endpoint doivent être testées par un test fonctionnel également.
- Un template de cas de test de ressource basée sur un modèle est proposé dans `tests/test_api/model_api_boilerplate.py`.
### Intégration frontend/backend
Le frontend est situé au même niveau que les autres applications Django, dans `oser_cs/frontend`. Ce dossier a été généré avec `create-react-app`.
Pour le développement, il faut mettre en route deux serveurs :
1. Le serveur Django, avec `python manage.py runserver` dans `oser_cs/`
2. Le serveur *hot-reload* de React, avec `npm start` dans `oser_cs/frontend`
Le site sera alors accessible à l'adresse `http://localhost:3000/`.
### Frontend
#### Configuration
https://stanko.github.io/webpack-babel-react-revisited/
## À propos d'OSER ## À propos d'OSER
......
...@@ -14,6 +14,7 @@ Cette documentation est destinée aux développeurs du site web d'OSER. Vous tro ...@@ -14,6 +14,7 @@ Cette documentation est destinée aux développeurs du site web d'OSER. Vous tro
:caption: Guide du développeur :caption: Guide du développeur
installation.rst installation.rst
pratiques-de-test.rst
documenter.rst documenter.rst
......
...@@ -2,15 +2,19 @@ ...@@ -2,15 +2,19 @@
Installation Installation
============ ============
Cette page vous indique étape par étape comme installer l'environnement de développement du site. À la fin de ce processus, vous aurez un serveur local fonctionnel ! Cette page vous indique étape par étape comme installer l'environnement de développement du site. À la fin de ce processus, vous aurez un site local fonctionnel !
Prérequis Prérequis
========= =========
Tout d'abord, 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 aurez aussi besoin de `Git <https://git-scm.com>`_ pour cloner le dépôt. Vous aurez besoin de `Git <https://git-scm.com>`_ pour cloner le dépôt.
Installer le serveur local Côté back, le site repose sur Django. 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.
==========================
Côté front, c'est React qui est utilisé. Vous allez donc avoir besoin de `npm <https://www.npmjs.com>`_ .
Installation des dépendances
============================
Tout d'abord, clonez le dépôt sur votre ordinateur : Tout d'abord, clonez le dépôt sur votre ordinateur :
:: ::
...@@ -26,9 +30,17 @@ Installez les dépendances Python en utilisant ``pip`` : ...@@ -26,9 +30,17 @@ Installez les dépendances Python en utilisant ``pip`` :
:: ::
(env) oser-website $ pip install -r requirements.txt (env) oser-website $ pip install -r requirements.txt
Configurez la BDD de développement : Rendez-vous ensuite dans ``oser_cs/frontend`` puis installez le package npm (cela prendra quelques minutes selon la vitesse de votre connexion internet) :
:: ::
(env) oser-website $ cd oser_cs (env) oser-website $ cd oser_cs/frontend
(env) frontend $ npm install
Configuration de la base de données
===================================
Tout d'abord, créez puis exécutez les migrations Django :
::
(env) frontend $ cd ..
(env) oser_cs $ python manage.py makemigrations (env) oser_cs $ python manage.py makemigrations
(env) oser_cs $ python manage.py migrate (env) oser_cs $ python manage.py migrate
...@@ -40,14 +52,69 @@ Si vous le souhaitez, vous pouvez peupler la BDD de développement avec des donn ...@@ -40,14 +52,69 @@ Si vous le souhaitez, vous pouvez peupler la BDD de développement avec des donn
:: ::
(env) oser_cs $ python manage.py populatedb (env) oser_cs $ python manage.py populatedb
Démarrez enfin le serveur local : Démarrage du site en mode développement
=======================================
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).
Démarrez le serveur local Django avec la commande `runserver` :
:: ::
(env) oser_cs $ python manage.py runserver (env) oser_cs $ python manage.py runserver
Le serveur local devrait se mettre en route et être accessible à l'URL ``http://localhost:8000/``. 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 !
Si vous vous rendez à l'adresse `http://localhost:8000/api/ <http://localhost:8000/api/>`_, vous arriverez à la racine de l'API :
.. image:: media/api_home.png .. image:: media/api_home.png
Et voilà, le serveur de développement est fonctionnel ! :) Pour le serveur front, rendez-vous dans `oser_cs/frontend` et démarrez le serveur npm :
::
oser_cs $ cd frontend/
frontend $ npm start
Une page de navigateur devrait s'ouvrir à l'adresse `http://localhost:3000/ <http://localhost:3000/>`_ avec 3 boutons vous invitant à envoyer des requêtes GET de test :
.. image:: media/front_home.png
Et voilà, le site tourne en mode développement !
Détail des dépendances
======================
Backend
-------
.. _Django : https://www.djangoproject.com
.. _release news: https://www.djangoproject.com/weblog/2017/dec/02/django-20-released/)
.. _Django REST Framework : http://www.django-rest-framework.org
.. _DRY Rest Permissions : https://github.com/dbkaplan/dry-rest-permissions
.. _FactoryBoy : http://factoryboy.readthedocs.io/en/latest/index.html
Django
******
Django_ est un framework de développement web pour Python.
Le site d'OSER utilise Django en version 2.0.
> À l'heure actuelle, peu de tutoriels Django se basent sur la version 2.0, mais il y a en fait très peu de changements non-rétro-compatibles par rapport à la version 1.11, et aucun changement n'est réellement critique. Les améliorations apportées par la version 2.0 sont intéressantes, on peut notamment citer le système d'écriture des URLs qui est grandement simplifié. Pour plus d'infos, lire la `release news`_ associée.
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.
DRY Rest Permissions
********************
`DRY Rest Permissions`_ est utilisé pour définir les permissions directement sur les modèles Django.
FactoryBoy
**********
`FactoryBoy`_ est utilisé pour faciliter la création d'objets de test en définissant des usines (*factories*) directement à partir des modèles Django. Les usines sont définies dans ``oser_cs/tests/factory.py``.
Frontend
--------
.. todo:: Lister les dépendances du frontend
docs/media/front_home.png

335 KiB

=================
Pratiques de test
=================
*Untested code is broken code.*
— Quelqu'un de connu
On ne rappellera jamais assez l'importance de tester le logiciel.
Si vous avez suivi le tutoriel d'installation, vous avez dû remarqué que l'on lançait des tests Django avec ``python manage.py test`` pour s'assurer que tout "allait bien" avant de démarrer les serveurs. C'est bien la preuve que des tests automatiques servent **d'assurance qualité**.
Pour garantir son fonctionnement et sa maintenabilité, **le code du site d'OSER doit être testé** le plus possible.
Conseils généraux
=================
- Dès que vous corrigez un bug, pensez à écrire un test de non-régression (qui permettra de s’assurer que le bug n’arrive plus).
- Tout élément de *business logic* devrait être testé par un test fonctionnel.
Concernant le backend
=====================
Test de l'API
-------------
- Les tests de l’API sont définis dans le package ``tests/test_api``.
- Tous les endpoints d’une ressource doivent être testés par un test fonctionnel qui envoie la requête et s’assure que le ``status_code`` est celui attendu.
- Les permissions d’un endpoint doivent être testées par un test fonctionnel également.
- Un template de cas de test de ressource basée sur un modèle est proposé dans ``tests/test_api/model_api_boilerplate.py``.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment