DocumentationCodeBonnesPratiques » Historique » Version 21
Version 20 (Daniel Dehennin, 11/06/2013 17:10) → Version 21/34 (Philippe Caseiro, 25/04/2014 10:41)
{{toc}}
h1. DocumentationCodeBonnesPratiques
**cette page concerne la documentation développeur**
(voir aussi [[TestsCodeBonnesPratiques]] pour les autres bonnes pratiques développeur)
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 juste après le "shebang":https://fr.wikipedia.org/wiki/Shebang, la déclaration d’"encodage des caractères":https://fr.wikipedia.org/wiki/Codage_de_caract%C3%A8res et la licence du code.
<pre>
#!/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
##########################################################################
</pre>
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 :
<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
comme pour la docstring des modules (mais sans la licence)
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
h2. 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
h2. Traduction et python
h1. DocumentationCodeBonnesPratiques
**cette page concerne la documentation développeur**
(voir aussi [[TestsCodeBonnesPratiques]] pour les autres bonnes pratiques développeur)
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 juste après le "shebang":https://fr.wikipedia.org/wiki/Shebang, la déclaration d’"encodage des caractères":https://fr.wikipedia.org/wiki/Codage_de_caract%C3%A8res et la licence du code.
<pre>
#!/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
##########################################################################
</pre>
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 :
<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
comme pour la docstring des modules (mais sans la licence)
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
h2. 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
h2. Traduction et python