DocumentationCodeBonnesPratiques » Historique » Version 20
Daniel Dehennin, 11/06/2013 17:10
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 |