EOLE

h1. DocumentationCodeBonnesPratiques

h2. Généralité

* La documentation technique doit être en anglais.
* Elle est placée placé dans les docstrings du code.

h2. Description du module

La docstring du module est placée en haut du fichier.

La docstring doit contenir :

* la licence du code

<pre>
###########################################################################
#
# EOLE
# Copyright Pole de Competence EOLE (Ministere Education - Academie Dijon)
# Licence CeCill http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html
# eole@ac-dijon.fr
#
###########################################################################
</pre>

* description rapide en une phrase du module ;
* description avancée qui explique le rôle du module ;
* des exemples simples d'utilisation.

Les exemples peuvent être un prompt :

<pre>
>>> is_locked()
True
</pre>

ou une portion de code :

<pre>
::

from toto.titi import is_locked

toto()
is_locked()
</pre>



h2. Docstring des méthodes

Seules les méthodes publiques (qui ne commencent pas par "_") seront mises dans la documentation (mais les méthodes privées sont aussi à documenter).

La docstring doit contenir :

* description rapide en une phrase de la méthode ;
* si nécessaire une description avancée qui explique le rôle du module ;
* si nécessaire des exemples simples d'utilisation.
* les paramètres de la façon suivante (xxx étant le nom du paramètre et yyyyyy la description) :

<pre>
:param xxx: yyyyyy
</pre>

Si nécessaire les valeurs de retour (yyyyyy étant la description) :

<pre>
:return: yyyyyy
</pre>

plus d'info sur la syntaxe des docstrings: http://sphinx-doc.org/domains.html#info-field-lists



h2. Docstring des classes

A faire