Projet

Général

Profil

DocumentationCodeBonnesPratiques » Historique » Version 7

« Précédent - Version 7/34 (diff) - Suivant » - Version actuelle
Emmanuel GARETTE, 12/12/2012 16:50


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.

La docstring doit contenir :

  • la licence du code
###########################################################################
# 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
###########################################################################
  • 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

A faire