DocumentationCodeBonnesPratiques¶

Généralité¶

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

Description du module¶

La docstring du module est placée en haut du fichier juste après le shebang, la déclaration d’encodage des caractères et la licence du code.

#!/usr/bin/python
# -*- coding: utf-8 -*-
#
###########################################################################
# EOLE
# Copyright Pôle de Compétence EOLE  (Ministère Éducation - Academie Dijon)
# Licence CeCILL en français http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html
# License CeCILL in english http://www.cecill.info/licences/Licence_CeCILL_V2-en.html
# eole@ac-dijon.fr
###########################################################################

La docstring doit contenir :

• 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 :

    >>> is_locked()
    True

ou une portion de code :

    ::

        from toto.titi import is_locked

        toto()
        is_locked()

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) :

    :param xxx: yyyyyy

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

    :return: yyyyyy

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

Docstring des classes¶

comme pour la docstring des modules (mais sans la licence)

Tips¶

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

 

:issue:`410` 

est un lien qui porte directement sur la demande 410

et

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

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