EOLE

h1. DocumentationCodeBonnesPratiques

h2. Généralité

* La documentation technique doit être en anglais.
* Elle est placée 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

h2. Tips

il est possible de faire un lien portant directement sur le redmine de deux manières :

<pre>

:issue:`410`

</pre>

est un lien qui porte directement sur la demande 410

et

<pre>

:eole:`/projects/creole/wiki/Lock24`

</pre>

qui est simplement un raccourci vers http://dev-eole.ac-dijon.fr/projects/creole/wiki/Lock24