EOLE

h1. DocumentationCodeBonnesPratiques

h2. Généralité

* La documentation technique doit être en anglais.

* Elle est 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