Write "documentation" section

source/part-1-workspace/django/_index.adoc

@@ -1,13 +1,13 @@
-== Django
+=== Notre première application Django
 
 Comme on l'a vu ci-dessus, `django-admin` permet de créer un nouveau projet. On fait ici une distinction entre un **projet** et une **application**:
 
  * **Projet**: ensemble des applications, paramètres, pages HTML, middlwares, dépendances, etc., qui font que votre code fait ce qu'il est sensé faire.
  * **Application**: *contexte* éventuellement indépendant, permettant d'effectuer une partie isolée de ce que l'on veut faire.
 
-Pour `gwift`, on va notamment avoir 
+Pour `gwift`, on va notamment avoir
 
-. une première application pour la gestion des listes de souhaits et des éléments, 
+. une première application pour la gestion des listes de souhaits et des éléments,
 . une deuxième application pour la gestion des utilisateurs,
 . voire une troisième application qui gérera les partages entre utilisateurs et listes.
 
@@ -93,13 +93,13 @@ Par soucis de clarté, déplacez ce nouveau répertoire `wish` dans votre réper
  * `models.py` pour représenter et structurer nos données.
  * `tests.py` pour les tests unitaires.
 
-  
+
 === Migrations et schéma de bases de données
-  
+
 https://simpleisbetterthancomplex.com/tutorial/2016/07/26/how-to-reset-migrations.html[reset migrations].
-  
-  En gros, soit on supprime toutes les migrations (en conservant le fichier __init__.py), soit on 
-  réinitialise proprement les migrations avec un --fake-initial (sous réserve que toutes les personnes qui 
+
+  En gros, soit on supprime toutes les migrations (en conservant le fichier __init__.py), soit on
+  réinitialise proprement les migrations avec un --fake-initial (sous réserve que toutes les personnes qui
   utilisent déjà le projet s'y conforment... Ce qui n'est pas gagné.
 
 === Tests unitaires
@@ -107,7 +107,7 @@ https://simpleisbetterthancomplex.com/tutorial/2016/07/26/how-to-reset-migration
 Plein de trucs à compléter ici ;-) Est-ce qu'on passe par pytest ou par le framework intégré ? Quels sont les avantages de l'un % à l'autre ?
  * `views.py` pour définir ce que nous pouvons faire avec nos données.
 
-NOTE: vérifier s'il s'agit bien d'une forme de convention :-p 
+NOTE: vérifier s'il s'agit bien d'une forme de convention :-p
 
 NOTE: Vérifier aussi comment les applications sont construites. Type DRF, Django Social Auth, tout ça.
 

source/part-1-workspace/documentation.adoc

@@ -4,8 +4,7 @@ Documentation: be obsessed!
 
 On en a déjà parlé plus haut, il existe un standard en Python pour la définition de la documentation du code: RST (et par extension, Sphinx, qui est le représentatn *de facto* pour la récupération du code d'une application et sa présentation dans un format souhaité: HTML, ePub, Latex, PDF, ...).
 
-Python étant un langage interprété fortement typé, il est plus que conseillé, au même titre que les tests unitaires, de documenter son code.
-Cela impose une certaine rigueur, mais améliore énormément la qualité (et la reprise) du code par une tierce personne. Cela implique aussi de **tout** documenter: les modules, les paquets, les classes, les fonctions, méthodes, ... Tout doit avoir un *docstring* associé :-).
+
 
 Plusieurs modules de documentation existent, mais nous allons nous concentrer sur Sphinx, qui semble être le plus complet et qui permet d'héberger directement sa documentation sur `ReadTheDocs.org <https://readthedocs.org/>`_. Nous allons également faire en sorte que cette documentation soit compatible avec Django, puisque c'est le but de notre projet.
 

source/part-1-workspace/environment/_index.adoc

@@ -13,6 +13,9 @@ Et malgré ces quelques points, Python reste un langage généraliste accessible
 Il 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 http://fr.wikipedia.org/wiki/Benevolent_Dictator_for_Life[Benevolent Dictator For Life].
 
+Si vous avez besoin d'un aide-mémoire ou d'une liste exhaustive des types et structures de données du langage, référez-vous au lien suivant: https://gto76.github.io/python-cheatsheet/[Python Cheat Sheet].
+
+NOTE: Le langage Python utilise un typage dynamique appelé https://fr.wikipedia.org/wiki/Duck_typing[*duck typing*]: "_When I see a bird that quacks like a duck, walks like a duck, has feathers and webbed feet and associates with ducks — I’m certainly going to assume that he is a duck_" (Source: http://en.wikipedia.org/wiki/Duck_test[Wikipedia (as usual)]).
 
 ==== PEP8 - Style Guide for Python Code
 
@@ -42,12 +45,71 @@ Il existe une solution qui couvre ces deux domaines: https://github.com/PyCQA/fl
 Sur base de la même interface que `pep8`, vous rencontreez en plus tous les avantages liés à `pyflakes`
 
 
-==== PEP257
+==== PEP257 - Docstring Conventions
 
-NOTE: à remplir avec `pydocstyle`.
+Python étant un langage interprété fortement typé, il est plus que conseillé, au même titre que les tests unitaires, de documenter son code.
+Cela impose une certaine rigueur, mais améliore énormément la qualité (et la reprise) du code par une tierce personne. Cela implique aussi de **tout** documenter: les modules, les paquets, les classes, les fonctions, méthodes, ... Tout doit avoir un *docstring* associé :-).
 
-NOTE: parler de Napoleon.
+Il existe plusieurs types de conventions de documentation:
 
+. PEP 257
+. Numpy
+. Google Style (parfois connue sous l'intitulé `Napoleon`)
+. ...
+
+Les https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings[conventions proposées par Google] nous semblent  plus faciles à lire que du RestructuredText, mais sont parfois moins bien intégrées que les docstrings officiellement supportées (typiquement, par exemple par https://clize.readthedocs.io/en/stable/[clize] qui ne reconnait que du RestructuredText).
+L'exemple donné dans les styleguide est celui-ci:
+
+[source,python]
+----
+def fetch_smalltable_rows(table_handle: smalltable.Table,
+                          keys: Sequence[Union[bytes, str]],
+                          require_all_keys: bool = False,
+) -> Mapping[bytes, Tuple[str]]:
+    """Fetches rows from a Smalltable.
+
+    Retrieves rows pertaining to the given keys from the Table instance
+    represented by table_handle.  String keys will be UTF-8 encoded.
+
+    Args:
+        table_handle: An open smalltable.Table instance.
+        keys: A sequence of strings representing the key of each table
+          row to fetch.  String keys will be UTF-8 encoded.
+        require_all_keys: Optional; If require_all_keys is True only
+          rows with values set for all keys will be returned.
+
+    Returns:
+        A dict mapping keys to the corresponding table row data
+        fetched. Each row is represented as a tuple of strings. For
+        example:
+
+        {b'Serak': ('Rigel VII', 'Preparer'),
+         b'Zim': ('Irk', 'Invader'),
+         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
+
+        Returned keys are always bytes.  If a key from the keys argument is
+        missing from the dictionary, then that row was not found in the
+        table (and require_all_keys must have been False).
+
+    Raises:
+        IOError: An error occurred accessing the smalltable.
+    """
+----
+
+C'est-à-dire:
+
+. Une courte ligne d'introduction, descriptive, indiquant ce que la fonction ou la méthode réalise. Attention, la documentation ne doit pas indiquer _comment_ la fonction/méthode est implémentée, mais ce qu'elle fait concrètement (et succintement).
+. Une ligne vide
+. Une description plus complète et plus verbeuse
+. Une ligne vide
+. La description des arguments et paramètres, des valeurs de retour (+ exemples) et les exceptions qui peuvent être levées.
+
+Un exemple (encore) plus complet peut être trouvé https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google[dans le dépôt sphinxcontrib-napoleon].
+
+Pour ceux que cela pourrait intéresser, il existe https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring[une extension pour Codium], comme nous le verrons juste après, qui permet de générer automatiquement le squelette de documentation d'un bloc de code:
+
+.autodocstring
+image::images/environment/python-docstring-vscode.png[]
 
 === Environnement de développement
 
@@ -117,10 +179,18 @@ Chaque "*commit*" correspond à une sauvegarde atomique d'un état ou d'un ensem
 De cette manière, il est beaucoup plus facile pour le développeur de se concenter sur un sujet en particulier, dans la mesure où celui-ci ne doit pas obligatoirement être clôturé pour appliquer un changement de contexte.
 
 .Git en action
-image::images/diagrams/git.png[]
+image::images/diagrams/git-workflow.png[]
 
 Cas pratique: vous développez cette nouvelle fonctionnalité qui va révolutionner le monde de demain et d'après-demain, quand, tout à coup (!), vous vous rendez compte que vous avez perdu votre conformité aux normes PCI parce les données des titulaires de cartes ne sont pas isolées correctement.
-Il suffit alors de sauver le travail en cours, revenir sur la branche principale, créer un "hotfix", solutionner le problème, pousser le correctif sur la branche principal, et revenir tranquillou sur votre branche de développement pour fignoler ce générateur de noms de dinosaures rigolos que l'univers vous réclame à cor et à a cri.
+Il suffit alors de
+
+. sauver le travail en cours (`git add . && git commit -m [WIP]`)
+. revenir sur la branche principale (`git checkout main`)
+. créer un "hotfix" (`git checkout -b hotfix/pci-compliance`)
+. solutionner le problème (sans doute un `;` en trop ?)
+. sauver le correctif sur cette branche (`git add . && git commit -m "Did it!"`)
+. récupérer ce correctif sur la branche principal (`git checkout main && git merge hotfix/pci-compliance`)
+. et revenir tranquillou sur votre branche de développement pour fignoler ce générateur de noms de dinosaures rigolos que l'univers vous réclame à cor et à a cri (`git checkout features/dinolol`)
 
 Finalement, sachez qu'il existe plusieurs manières de gérer ces flux d'informations.
 Les plus connus sont https://www.gitflow.com/[Gitflow] et https://www.reddit.com/r/programming/comments/7mfxo6/a_branching_strategy_simpler_than_gitflow/[Threeflow].

source/part-1-workspace/python.adoc

@@ -1,3 +0,0 @@
-https://gto76.github.io/python-cheatsheet/[Python Cheat Sheet]
-
-*duck typing*: "_When I see a bird that quacks like a duck, walks like a duck, has feathers and webbed feet and associates with ducks—I’m certainly going to assume that he is a duck_" (Source: http://en.wikipedia.org/wiki/Duck_test[Wikipedia (as usual)]).