Projet

Général

Profil

DocumentationCodeBonnesPratiques » Historique » Version 21

Philippe Caseiro, 25/04/2014 10:41

1 20 Daniel Dehennin
{{toc}}
2 20 Daniel Dehennin
3 1 Emmanuel GARETTE
h1. DocumentationCodeBonnesPratiques
4 1 Emmanuel GARETTE
5 18 Gwenael Remond
**cette page concerne la documentation développeur**
6 18 Gwenael Remond
(voir aussi [[TestsCodeBonnesPratiques]] pour les autres bonnes pratiques développeur)
7 18 Gwenael Remond
8 1 Emmanuel GARETTE
h2. Généralité
9 1 Emmanuel GARETTE
10 1 Emmanuel GARETTE
* La documentation technique doit être en anglais.
11 5 Gérald Schwartzmann
* Elle est placée dans les docstrings du code.
12 1 Emmanuel GARETTE
13 1 Emmanuel GARETTE
h2. Description du module
14 1 Emmanuel GARETTE
15 12 Daniel Dehennin
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.
16 2 Gwenael Remond
17 1 Emmanuel GARETTE
<pre>
18 12 Daniel Dehennin
#!/usr/bin/python
19 12 Daniel Dehennin
# -*- coding: utf-8 -*-
20 12 Daniel Dehennin
#
21 16 Emmanuel GARETTE
##########################################################################
22 16 Emmanuel GARETTE
# <nom du projet>
23 19 Daniel Dehennin
# Copyright © 2013 Pôle de compétences EOLE <eole@ac-dijon.fr>
24 14 Daniel Dehennin
#
25 16 Emmanuel GARETTE
# License CeCILL:
26 16 Emmanuel GARETTE
#  * in french: http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html
27 16 Emmanuel GARETTE
#  * in english http://www.cecill.info/licences/Licence_CeCILL_V2-en.html
28 16 Emmanuel GARETTE
##########################################################################
29 2 Gwenael Remond
</pre>
30 2 Gwenael Remond
31 11 Daniel Dehennin
La docstring doit contenir :
32 1 Emmanuel GARETTE
* description rapide en une phrase du module ;
33 1 Emmanuel GARETTE
* description avancée qui explique le rôle du module ;
34 1 Emmanuel GARETTE
* des exemples simples d'utilisation.
35 1 Emmanuel GARETTE
36 1 Emmanuel GARETTE
Les exemples peuvent être un prompt :
37 1 Emmanuel GARETTE
38 1 Emmanuel GARETTE
<pre>
39 1 Emmanuel GARETTE
    >>> is_locked()
40 1 Emmanuel GARETTE
    True
41 1 Emmanuel GARETTE
</pre>
42 1 Emmanuel GARETTE
43 1 Emmanuel GARETTE
ou une portion de code :
44 1 Emmanuel GARETTE
45 1 Emmanuel GARETTE
<pre>
46 1 Emmanuel GARETTE
    ::
47 1 Emmanuel GARETTE
48 1 Emmanuel GARETTE
        from toto.titi import is_locked
49 1 Emmanuel GARETTE
50 1 Emmanuel GARETTE
        toto()
51 1 Emmanuel GARETTE
        is_locked()
52 1 Emmanuel GARETTE
</pre>
53 1 Emmanuel GARETTE
54 1 Emmanuel GARETTE
h2. Docstring des méthodes
55 1 Emmanuel GARETTE
56 3 Gwenael Remond
Seules les méthodes publiques (qui ne commencent pas par "_") seront mises dans la documentation (mais les méthodes privées sont aussi à documenter).
57 1 Emmanuel GARETTE
58 1 Emmanuel GARETTE
La docstring doit contenir :
59 1 Emmanuel GARETTE
60 1 Emmanuel GARETTE
* description rapide en une phrase de la méthode ;
61 1 Emmanuel GARETTE
* si nécessaire une description avancée qui explique le rôle du module ;
62 1 Emmanuel GARETTE
* si nécessaire des exemples simples d'utilisation.
63 1 Emmanuel GARETTE
* les paramètres de la façon suivante (xxx étant le nom du paramètre et yyyyyy la description) :
64 1 Emmanuel GARETTE
65 1 Emmanuel GARETTE
<pre>
66 1 Emmanuel GARETTE
    :param xxx: yyyyyy
67 1 Emmanuel GARETTE
</pre>
68 1 Emmanuel GARETTE
69 1 Emmanuel GARETTE
Si nécessaire les valeurs de retour (yyyyyy étant la description) :
70 1 Emmanuel GARETTE
71 1 Emmanuel GARETTE
<pre>
72 1 Emmanuel GARETTE
    :return: yyyyyy
73 1 Emmanuel GARETTE
</pre>
74 1 Emmanuel GARETTE
75 4 Gwenael Remond
plus d'info sur la syntaxe des docstrings: http://sphinx-doc.org/domains.html#info-field-lists
76 4 Gwenael Remond
77 1 Emmanuel GARETTE
h2. Docstring des classes
78 1 Emmanuel GARETTE
79 10 Gwenael Remond
comme pour la docstring des modules (mais sans la licence)
80 8 Gwenael Remond
81 8 Gwenael Remond
h2. Tips
82 8 Gwenael Remond
83 8 Gwenael Remond
il est possible de faire un lien portant directement sur le redmine de deux manières :
84 8 Gwenael Remond
85 8 Gwenael Remond
<pre> 
86 8 Gwenael Remond
87 8 Gwenael Remond
:issue:`410` 
88 8 Gwenael Remond
89 8 Gwenael Remond
</pre> 
90 8 Gwenael Remond
91 8 Gwenael Remond
est un lien qui porte directement sur la demande 410
92 8 Gwenael Remond
93 8 Gwenael Remond
et
94 8 Gwenael Remond
95 8 Gwenael Remond
<pre>
96 8 Gwenael Remond
97 8 Gwenael Remond
 :eole:`/projects/creole/wiki/Lock24`
98 8 Gwenael Remond
99 8 Gwenael Remond
</pre>
100 8 Gwenael Remond
101 8 Gwenael Remond
qui est simplement un raccourci vers http://dev-eole.ac-dijon.fr/projects/creole/wiki/Lock24
102 17 Daniel Dehennin
103 17 Daniel Dehennin
h2. Exemples
104 17 Daniel Dehennin
105 17 Daniel Dehennin
Plusieurs fichiers sources ont reçu une attention assez particulière sur la documentation :
106 17 Daniel Dehennin
107 17 Daniel Dehennin
- python-pyeole:source:pyeole/decorator.py
108 17 Daniel Dehennin
- python-pyeole:source:pyeole/log.py
109 17 Daniel Dehennin
- python-pyeole:source:pyeole/lock.py
110 21 Philippe Caseiro
111 21 Philippe Caseiro
h2. Traduction et python