Projet

Général

Profil

DocumentationCodeBonnesPratiques » Historique » Version 9

Gwenael Remond, 13/12/2012 16:29

1 1 Emmanuel GARETTE
h1. DocumentationCodeBonnesPratiques
2 1 Emmanuel GARETTE
3 1 Emmanuel GARETTE
h2. Généralité
4 1 Emmanuel GARETTE
5 1 Emmanuel GARETTE
* La documentation technique doit être en anglais.
6 5 Gérald Schwartzmann
* Elle est placée dans les docstrings du code.
7 1 Emmanuel GARETTE
8 1 Emmanuel GARETTE
h2. Description du module
9 1 Emmanuel GARETTE
10 1 Emmanuel GARETTE
La docstring du module est placée en haut du fichier.
11 1 Emmanuel GARETTE
12 1 Emmanuel GARETTE
La docstring doit contenir :
13 1 Emmanuel GARETTE
14 2 Gwenael Remond
* la licence du code 
15 2 Gwenael Remond
16 2 Gwenael Remond
<pre>
17 2 Gwenael Remond
###########################################################################
18 2 Gwenael Remond
# EOLE
19 2 Gwenael Remond
# Copyright Pole de Competence EOLE  (Ministere Education - Academie Dijon)
20 6 Gérald Schwartzmann
# Licence CeCILL  http://www.cecill.info/licences/Licence_CeCILL_V2-fr.html
21 2 Gwenael Remond
# eole@ac-dijon.fr
22 2 Gwenael Remond
###########################################################################
23 2 Gwenael Remond
</pre>
24 2 Gwenael Remond
25 1 Emmanuel GARETTE
* description rapide en une phrase du module ;
26 1 Emmanuel GARETTE
* description avancée qui explique le rôle du module ;
27 1 Emmanuel GARETTE
* des exemples simples d'utilisation.
28 1 Emmanuel GARETTE
29 1 Emmanuel GARETTE
Les exemples peuvent être un prompt :
30 1 Emmanuel GARETTE
31 1 Emmanuel GARETTE
<pre>
32 1 Emmanuel GARETTE
    >>> is_locked()
33 1 Emmanuel GARETTE
    True
34 1 Emmanuel GARETTE
</pre>
35 1 Emmanuel GARETTE
36 1 Emmanuel GARETTE
ou une portion de code :
37 1 Emmanuel GARETTE
38 1 Emmanuel GARETTE
<pre>
39 1 Emmanuel GARETTE
    ::
40 1 Emmanuel GARETTE
41 1 Emmanuel GARETTE
        from toto.titi import is_locked
42 1 Emmanuel GARETTE
43 1 Emmanuel GARETTE
        toto()
44 1 Emmanuel GARETTE
        is_locked()
45 1 Emmanuel GARETTE
</pre>
46 1 Emmanuel GARETTE
47 1 Emmanuel GARETTE
h2. Docstring des méthodes
48 1 Emmanuel GARETTE
49 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).
50 1 Emmanuel GARETTE
51 1 Emmanuel GARETTE
La docstring doit contenir :
52 1 Emmanuel GARETTE
53 1 Emmanuel GARETTE
* description rapide en une phrase de la méthode ;
54 1 Emmanuel GARETTE
* si nécessaire une description avancée qui explique le rôle du module ;
55 1 Emmanuel GARETTE
* si nécessaire des exemples simples d'utilisation.
56 1 Emmanuel GARETTE
* les paramètres de la façon suivante (xxx étant le nom du paramètre et yyyyyy la description) :
57 1 Emmanuel GARETTE
58 1 Emmanuel GARETTE
<pre>
59 1 Emmanuel GARETTE
    :param xxx: yyyyyy
60 1 Emmanuel GARETTE
</pre>
61 1 Emmanuel GARETTE
62 1 Emmanuel GARETTE
Si nécessaire les valeurs de retour (yyyyyy étant la description) :
63 1 Emmanuel GARETTE
64 1 Emmanuel GARETTE
<pre>
65 1 Emmanuel GARETTE
    :return: yyyyyy
66 1 Emmanuel GARETTE
</pre>
67 1 Emmanuel GARETTE
68 4 Gwenael Remond
plus d'info sur la syntaxe des docstrings: http://sphinx-doc.org/domains.html#info-field-lists
69 4 Gwenael Remond
70 1 Emmanuel GARETTE
h2. Docstring des classes
71 1 Emmanuel GARETTE
72 9 Gwenael Remond
comme pour la docstring des modules
73 8 Gwenael Remond
74 8 Gwenael Remond
h2. Tips
75 8 Gwenael Remond
76 8 Gwenael Remond
il est possible de faire un lien portant directement sur le redmine de deux manières :
77 8 Gwenael Remond
78 8 Gwenael Remond
<pre> 
79 8 Gwenael Remond
80 8 Gwenael Remond
:issue:`410` 
81 8 Gwenael Remond
82 8 Gwenael Remond
</pre> 
83 8 Gwenael Remond
84 8 Gwenael Remond
est un lien qui porte directement sur la demande 410
85 8 Gwenael Remond
86 8 Gwenael Remond
et
87 8 Gwenael Remond
88 8 Gwenael Remond
<pre>
89 8 Gwenael Remond
90 8 Gwenael Remond
 :eole:`/projects/creole/wiki/Lock24`
91 8 Gwenael Remond
92 8 Gwenael Remond
</pre>
93 8 Gwenael Remond
94 8 Gwenael Remond
qui est simplement un raccourci vers http://dev-eole.ac-dijon.fr/projects/creole/wiki/Lock24