• DocumentationCodeBonnesPratiques
  • Généralité
  • Description du module
  • Docstring des méthodes
  • Docstring des classes
  • Tips
  • Exemples
  • Traduction et python
    • i18n.py

DocumentationCodeBonnesPratiques¶

cette page concerne la documentation développeur
(voir aussi TestsCodeBonnesPratiques pour les autres bonnes pratiques développeur)

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 -*-
#
##########################################################################
# <nom du projet>
# Copyright © 2013 Pôle de compétences EOLE <eole@ac-dijon.fr>
#
# License CeCILL:
#  * in french: http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html
#  * in english http://www.cecill.info/licences/Licence_CeCILL_V2-en.html
##########################################################################

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

Exemples¶

Plusieurs fichiers sources ont reçu une attention assez particulière sur la documentation :

- python-pyeole:source:pyeole/decorator.py
- python-pyeole:source:pyeole/log.py
- python-pyeole:source:pyeole/lock.py

Traduction et python¶

Voici un petit aide mémoire pour traduire une application python de la manière la plus simple possible.

Pour traduire une application il faut en premier lieux une bibliothèque qui gère les traductions, la première
qui viens à l'esprit est gettext, donc logiquement nous allons nous tourner vers python-gettext.

Il faut noter qu'il est important de faire les choses dans l'ordre, les messages par défaut des applications doivent être dans une seule et unique langue, l'usage
est de tout écrire en anglais et ensuite de mettre une traduction pour les autres langues.

Le principe de gettext est de remplacer tous les messages par l'appel à une "fonction/méthode/whatever" qui vais
faire les opérations de traduction.

Dans le monde gettext cette "fonction" a pour nom '_'.

La première chose a faire est de mettre a disposition une "fonction" '_' dans votre appli python. (Les exemples suivants proviennent de pyeole)

i18n.py¶

On crée un "module" i18n.py (mais il pourrais très bien avoir un autre nom) et on y fait les déclarations et les initialisation nécessaires pour la traduction.

• Dans ce module on importe gettext et les modules nécessaires a la gestion de la traduction (python-gettext)
  

  import gettext # Gettext lui même
  import os      # Pour les variables d'environement LANG/LC_ALL
  import sys     # Pour la gestion des fichiers de traduction
  import locale  # Pour la gestion des "locale" 
  

• On définis le nom du domaine de traduction (le plus souvent le nom de l'application)
  

  APP_NAME = 'pyeole'
  

• On récupère les répertoires qui vont contentir les traductions
  

  # Traduction dir
  APP_DIR = os.path.join(sys.prefix, 'share')
  LOCALE_DIR = os.path.join(APP_DIR, 'locale')
  

• On récupère la langue par défaut et on y ajoute l'anglais pour les messages non traduits

1. Default Lanugage
   DEFAULT_LANG = os.environ.get('LANG', '').split(':')
   DEFAULT_LANG += ['en_US']

languages = []
lc, encoding = locale.getdefaultlocale()
if lc:
languages = [lc]

languages += DEFAULT_LANG
mo_location = LOCALE_DIR

gettext.find(APP_NAME, mo_location)
gettext.textdomain(APP_NAME)
gettext.bind_textdomain_codeset(APP_NAME, "UTF-8")

t = gettext.translation(APP_NAME, fallback=True)

def _(msg):
return t.ugettext(msg)