From 6e9c75c094831fa03602b57a095e6ad5699fa528 Mon Sep 17 00:00:00 2001
From: Fred Pauchet <frederick.pauchet@erasme.ulb.ac.be>
Date: Wed, 7 Oct 2015 14:12:16 +0200
Subject: [PATCH] add pep8

---
 book/fr/step-02-create-django-app.md    | 13 ++++-----
 book/fr/step-03-before-going-further.md | 39 +++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 7 deletions(-)
 create mode 100644 book/fr/step-03-before-going-further.md

diff --git a/book/fr/step-02-create-django-app.md b/book/fr/step-02-create-django-app.md
index f13d910..a801323 100644
--- a/book/fr/step-02-create-django-app.md
+++ b/book/fr/step-02-create-django-app.md
@@ -19,7 +19,7 @@ Comme expliqué un peu plus haut, le fichier `manage.py` est un *wrapper* sur le
  * `manage.py runserver` pour lancer un serveur de développement
  * `manage.py test` pour découvrir les tests unitaires disponibles et les lancer.
 
-La liste complète peut être affichée avec `manage.py help`. Vous remarquerez que ces commandes sont groupées: 
+La liste complète peut être affichée avec `manage.py help`. Vous remarquerez que ces commandes sont groupées:
 
  * **auth**: création d'un nouveau super-utilisateur, changer le mot de passe pour un utilisateur existant.
  * **django**: vérifier la *compliance* du projet, lancer un *shell*, *dumper* les données de la base, effectuer une migration du schéma, ...
@@ -31,22 +31,22 @@ Nous verrons plus tard comment ajouter de nouvelles commandes.
 Structure d'une application
 ---------------------------
 
-Maintenant que l'on a vu à quoi servait `manage.py`, on peut créer notre nouvelle application grâce à la commande `manage.py startapp <label>`. 
+Maintenant que l'on a vu à quoi servait `manage.py`, on peut créer notre nouvelle application grâce à la commande `manage.py startapp <label>`.
 Cette application servira à structurer les listes de souhaits, les éléments qui les composent et les parties que chaque utilisateur pour offrir. Essayez de trouver un nom éloquent, court et qui résume bien ce que fait l'application. Pour nous, ce sera donc `wish`. C'est parti pour `manage.py startapp wish`!
 
 ```shell
 $ cd gwift
 $ python manage.py startapp wish
-``` 
+```
 
-Résultat? Django nous a créé un répertoire `wish`, dans lequel on trouve les fichiers suivants: 
+Résultat? Django nous a créé un répertoire `wish`, dans lequel on trouve les fichiers suivants:
 
 ```shell
 $ ls -l wish
 admin.py  __init__.py  migrations  models.py  tests.py  views.py
-``` 
+```
 
-En résumé, chaque fichier a la fonction suivante: 
+En résumé, chaque fichier a la fonction suivante:
 
  * `admin.py` servira à structurer l'administration de notre application. Chaque information peut en effet être administrée facilement au travers d'une interface générée à la volée par le framework. On y reviendra par la suite.
  * `__init__.py` pour que notre répertoire `wish` soit converti en package Python.
@@ -54,4 +54,3 @@ En résumé, chaque fichier a la fonction suivante:
  * `models.py` pour représenter et structurer nos données.
  * `tests.py` pour les tests unitaires.
  * `views.py` pour définir ce que nous pouvons faire avec nos données.
-
diff --git a/book/fr/step-03-before-going-further.md b/book/fr/step-03-before-going-further.md
new file mode 100644
index 0000000..00fb400
--- /dev/null
+++ b/book/fr/step-03-before-going-further.md
@@ -0,0 +1,39 @@
+Avant d'aller plus loin...
+==========================
+
+Avant d'aller plus loin, donc, un petit point sur les conventions, les tests (unitaires, orientés comportement, basés sur la documentation, ...) et sur la documentation. Plus que dans tout langage compilé, ceux-ci sont pratiquement obligatoires. Vous pourrez les voir comme une perte de temps dans un premier temps, mais nous vous promettons qu'ils vous en feront gagner par la suite.
+
+## PEP8
+
+Le langage Python fonctionne avec un système d'améliorations basées sur des propositions: les PEP, ou "Python Enhancement Proposal". Chacune d'entre elles doit être approuvée par le [Benevolent Dictator For Life](http://fr.wikipedia.org/wiki/Benevolent_Dictator_for_Life).
+
+La PEP qui nous intéresse plus particulièrement pour la suite est la [PEP-8](https://www.python.org/dev/peps/pep-0008/), ou "Style Guide for Python Code". Elle spécifie des conventions d'organisation et de formatage de code Python, quelles sont les conventions pour l'indentation, le nommage des variables et des classes, ... En bref, elle décrit comment écrire du code proprement pour que d'autres développeurs puissent le reprendre facilement, ou simplement que votre base de code ne dérive lentement vers un seuil de non-maintenabilité.
+
+Sur cette base, un outil existe et listera l'ensemble des conventions qui ne sont pas correctement suivies dans votre projet: pep8. Pour l'installer, passez par pip. Lancez ensuite la commande pep8 suivie du chemin à analyser (., le nom d'un répertoire, le nom d'un fichier `.py`, ...). Si vous souhaitez uniquement avoir le nombre d'erreur de chaque type, saisissez les options `--statistics -qq`.
+
+```shell
+$ pep8 . --statistics -qq
+
+7       E101 indentation contains mixed spaces and tabs
+6       E122 continuation line missing indentation or outdented
+8       E127 continuation line over-indented for visual indent
+23      E128 continuation line under-indented for visual indent
+3       E131 continuation line unaligned for hanging indent
+12      E201 whitespace after '{'
+13      E202 whitespace before '}'
+86      E203 whitespace before ':'
+```
+
+Si vous ne voulez pas être dérangé sur votre manière de coder, et que vous voulez juste avoir un retour sur une analyse de votre code, essayez `pyflakes`: il analysera vos sources à la recherche de sources d'erreurs possibles (imports inutilisés, méthodes inconnues, etc.).
+
+Finalement, la solution qui couvre ces deux domaines existe et s'intitule [flake8](https://github.com/PyCQA/flake8). Sur base la même interface que `pep8`, vous aurez en plus tous les avantages liés à `pyflakes` concernant votre code source.
+
+## Tests et couverture de code
+
+La couverture de code donne un pourcentage lié à la quantité de code couvert par les testss.
+Attention que celle-ci ne permet pas de vérifier que le code est **bien** testé, elle permet juste de vérifier que le code est **testé**. Pour chaque fonction ou *statement* présent.
+
+
+## Documentation
+
+Il existe plusieurs manières de générer la documentation d'un projet. Les plus connues sont [Sphinx](http://sphinx-doc.org/) et [MkDocs](http://www.mkdocs.org/). Le premier a l'avantage d'être plus reconnu dans la communauté Python que l'autre, de pouvoir *parser* le code pour en extraire la documentation et de pouvoir lancer des [tests orientés documentation](https://duckduckgo.com/?q=documentation+driven+development&t=ffsb). A contrario, votre syntaxe devra respecter [ReStructuredText](https://en.wikipedia.org/wiki/ReStructuredText). Le second a l'avantage d'avoir une syntaxe plus simple à apprendre et à comprendre, mais est plus limité dans son résultat.