EPYDOC : Génération de documentation API pour PYTHON

GALODE Alexandre

Une bonne documentation est indispensable pour tout développement, aussi bien pour la compréhension du code, que pour sa maintenance et sa viabilité dans le temps.

Cette documentation est généralement divisée en trois grandes parties : les commentaires de code, la documentation technique du code et la documentation fonctionnelle du code.

Afin de faciliter la rédaction des documentations techniques et fonctionnelles du code, chaque langage dispose de ses propres outils plus ou moins évolués.

Nous allons ici voir l'un d'entre eux afin d'automatiser la documentation technique du code.

- Titre : EPYDOC : Génération de documentation API pour PYTHON

- Auteur : GALODE Alexandre

- Parution : 10 janvier 2014

- Mise à jour : 10 janvier 2014

- Public visé :

- Licence : Le contenu de cet article est rédigé par GALODE Alexandre et est mis à disposition selon les termes de la Licence Creative Commons Attribution 3.0 non transposé. Les logos Developpez.com, en-tête, pied de page, css, et look & feel de l'article sont Copyright ® 2013 Developpez.com.

Sommaire

- I. Introduction

- II. Fonctionnement

- II-A. Principe

- II-B. Langages reconnus

- II-B-1. Paragraphe

- II-B-2. List

- II-B-3. Sections

- II-B-4. Literal block

- II-B-5. Field

- II-C. Quelques possibilités supplémentaires

- II-C-1. Mise en forme interne

- II-C-2. Génération de graphismes

- II-C-3. Mise en page de la documentation via CSS

- III. Interface

- III-A. Ligne de commande

- III-B. GUI

- III-B-1. Partie 1 : Les modules/packages à documenter

- III-B-2. Partie 2 : La génération de la documentation

- III-B-3. Partie 3 : Les options projet

- III-B-4. Partie 4 : La configuration de l'aide

- III-B-5. Partie 5 : Le style de mise en page

- IV. Mise en pratique

- IV-A. Génération de la documentation

- V. Conclusion

- VI. Remerciements

I - Introduction

Python dispose d'un certain nombre d'outils pour documenter ses sources. Le plus connu du moment est probablement Sphinx. Mais cet outil n'est pas le premier a avoir existé.

Il existe en effet Epydoc, datant du début des années 2000 et qui, bien qu'un peu brut de décoffrage, s'avère on ne peut plus simple à l'usage.

Ce tutoriel ne cherche nullement à se substituer à la documentation officielle. Il vise à donner l'ensemble des bases nécessaires à une utilisation correcte de l'outil, tout en essayant d'être le plus explicite possible.

II - Fonctionnement

II-A - Principe

Pour générer cette documentation technique, Epydoc se base sur les docstrings du code.

Pour ce faire il faut utiliser l'une des syntaxes reconnues par Epydoc. Chacune de ces syntaxes possibles sera plus ou moins lisible humainement parlant. Cependant, choisir de travailler avec Epydoc, signifie également devoir renoncer tout ou partie à sa technique de codage/d'utilisation des docstrings.

Une fois les docstrings correctement alimentées, l'appel à l'outil, via ligne de commande ou IHM au choix, permet de générer la documentation, en général au format HTML.

Cette documentation HTML, générée dans un dossier, est alors consultable à volonté hors ligne, un peu à l'image de la javadoc HTML.

Mon expérience personnelle de cet outil m'a démontré qu'Epydoc semble préférer de loin les tabulations aux espaces pour l'indentation. Je ne peux donc que vous recommander d'utiliser des tabulations pour l'indentation de l'ensemble de votre code.

II-B - Langages reconnus

Comme explicité au-dessus, Epydoc sait gérer différentes syntaxes plus ou moins standardisées. Nous verrons ici les grandes lignes des principales syntaxes. Pour celles qui ne seront pas abordées ici, je vous renvoie à la documentation officielle.

L'ensemble de ces langages est connu sous le nom d'Epytext. Il faut comprendre dans ce terme, la mise en œuvre d'un formalisme permettant de créer des docstrings à la fois lisibles humainement et logiciellement par Epydoc.

Remarque : Epydoc exige qu'un caractère soit placé dès l'ouverture des docstrings. Vous ne pouvez ainsi pas passer une ou plusieurs lignes entre l'ouverture de la docstring et votre texte.

Les Epytext savent gérer différents niveaux d'importance, un peu comme des titres dans un ouvrage (titre de niveau1, titre de niveau2…). Afin de distinguer correctement ces niveaux, Epydoc utilise l'indentation. Les exemples qui suivent seront je le pense, suffisamment parlants. Ces exemples sont tirés tout ou partie du site officiel d'Epydoc.

II-B-1 - Paragraphe

La documentation la plus simple. Elle consiste simplement en une syntaxe textuelle. Vous y décrivez simplement au format texte les entrées/sorties, paramètres…

Docstring

Rendu final type

def example():
"""
Ceci est une docstring
Elle est constituée de
deux paragraphes.
"""
<CODE ...>

Ceci est une docstring
Elle est constituée de deux paragraphes.

II-B-2 - List

L'Epytext list consiste à l'utilisation d'un index pour organiser un peu plus clairement les informations que l'Epytext paragraphe. L'index doit être suivi d'un point puis d'un espace.

Vous pouvez passer des lignes entre chaque index dans la docstring, mais ces lignes vides de séparations ne seront pas répercutées dans la documentation générée.

Docstring

Rendu final type

def example():
"""
1. Ceci est le point 1
2. Second point
3. Dernier point
"""
<CODE ...>

1. Ceci est le point 1
2. Second point
3. Dernier point

Une liste peut contenir des sous-listes et des sous-sous-listes. Pour cela, il faut utiliser le caractère « - », suivi encore une fois d'un espace.

Docstring

Rendu final type

def example():
"""
1. Ceci est le premier point
2. Second point
- sous liste
- sous sous liste
3. Dernier point
"""
<CODE ...>

1. Ceci est le premier point
2. Second point
• sous liste
⁃ sous sous liste
3. Dernier point

Vous avez également la possibilité de mixer Epytext paragraphe et liste. L'Epytext paragraphe est considéré comme étant d'un niveau supérieur à l'Epytext liste. Ce faisant, les sauts de lignes vides seront interprétés comme tels.

Docstring

Rendu final type

def example():
"""
Ceci est une docstring
1. Ceci est le point 1
2. Second point
3. Dernier point
"""
<CODE ...>

Ceci est une docstring
1. Ceci est le point 1
2. Second point
3. Dernier point

II-B-3 - Sections

Cet Epytext reste à la fois relativement verbeux pour être lisible sans effort, utilise un formalisme minimum permettant une docstring propre, et permet de générer une documentation également très lisible. Cela tient beaucoup à la mise en forme des titres de sections.

Trois niveaux sont disponibles. Chaque niveau dispose d'un titre, ainsi que d'une section texte, type paragraphe. Chaque titre de niveau est souligné d'un caractère spécifique.

Niveau de la section

Caractère spécifique

1

=

2

-

3

~

Attention : Le nombre de caractères spécifiques, permettant d'identifier le niveau de la section, doit être strictement identique au nombre de caractères alphanumériques, espaces inclus, composants le nom de la section.

Docstring

Rendu final type

def example(param1, param2):
"""
Ceci est la description de la fonction
Parametres
==========
param1
------
Explication du param1
param2
------
Explication du param2
Note
~~~~
section de niveau 3
Retour
======
Retourne True ou False
"""
<CODE ...>

Ceci est la description de la fonction
Parametres
param1
Explication du param1
param2
Explication du param2
Note
section de niveau 3
Retour
Retourne True ou False

II-B-4 - Literal block

Les Literal Blocks n'ont à mon sens que peu d'intérêt, même si certains leur trouveront probablement une utilité.

Ces blocs sont introduits par un Epytext paragraphe se terminant par « :: ». Leur indentation dans le rendu final prend comme référence l'Epytext paragraphe l'ayant introduit.

L'Epytext Literal Block sortira dans la documentation tel qu'il a été saisi dans la docstring.

Le bloc littéral se termine lorsque qu'un Epytext se trouve à la même indentation que l'Epytext paragraphe l'ayant introduit.

Docstring

Rendu final type

def example():
"""
Bloc litteral::
Ce texte apparaitra//\
tel \\
quel
Fin du bloc litteral
"""
<CODE ...>

Bloc litteral:
Ce texte apparaitra//\
tel \\
quel
Fin du bloc litteral

II-B-5 - Field

L'Epytext le plus complet, permettant de générer la meilleure documentation, mais probablement également la moins lisible malheureusement dans le code.

L'Epytext Field se base sur des expressions clés afin de générer la documentation. Ces mots clés sont classés en différentes catégories :

- fonctions & méthodes ;

- variables ;

- notes ;

- statut ;

- prérequis ;

- bibliographie ;

- autre.

Chacune de ces expressions clés doit être suivie par « : » puis d'un espace.

Catégorie

expression clé

Description

Fonctions & méthodes

@param p

Permet de décrire le paramètre p

@type p

Le type du paramètre p

@return

Ce qui est retourné

@rtype

Le type de ce qui est retourné

Variables

@var v

Permet de décrire la variable v

@type v

Le type de la variable v

Notes

@note

Permet de laisser une note

@attention

Permet de laisser un message important

@bug

Permet de laisser une note à propos d'un bug connu

@warning

Permet de laisser un avertissement

Statut

@version

La version en cours

Prérequis

@requires

Prérequis au bon fonctionnement du code

Bibliographie

@author

L'auteur du code

@organization

La société émettrice du code

@copyright

Information à propos du copyright

@license

La licence sous laquelle est placé le code

@contact

Les contacts en cas de problème, question

Autre

@summary

Un résumé de ce que fait le code

Docstring

def example():
"""
@param x: This is a description of
the parameter x to a function.
Note that the description is
indented four spaces.
@type x: This is a description of
x's type.
@return: This is a description of
the function's return value.
It contains two paragraphs.
"""
<CODE ...>

Rendu final type

Parameters:
x - This is a description of the parameter x to a function. Note that the description is indented four spaces.
(type=This is a description of x's type.)
Returns:
This is a description of the function's return value.
It contains two paragraphs.

II-C - Quelques possibilités supplémentaires

II-C-1 - Mise en forme interne

Il vous est parfaitement possible de réaliser de la mise en forme interne. Compatible avec l'ensemble des Epytext, cette mise en forme repose sur l'encadrement des éléments à mettre en forme, entre parenthèses. Ces parenthèses seront alors précédées de lettres majuscules permettant de définir la mise en forme à appliquer.

Formalisme

Description

I{…}

Permet de mettre du texte en italique

B{…}

Permet de mettre du texte en gras

C{…}

Permet une mise en forme de type code

U{…}

Permet d'indiquer une URL

E{…}

Permet l'échappement d'un caractère Epytext (=, -, ~, :, " rb " pour " } ", " lb " pour " {" )

II-C-2 - Génération de graphismes

Epydoc peut générer automatiquement dans la documentation des graphiques descriptifs. Pour cela, Epydoc se base sur Graphviz.

Les graphiques peuvent être de quatre types. On les crée en utilisant la commande G{...}.

G{classtree}

À mettre dans la docstring d'une classe. Permet de générer un graphique contenant l'arbre d'héritage de la classe

G{packagetree}

À mettre dans la docstring d'un package (fichier __init__.py). Permet de générer un graphique contenant l'arbre du package.

G{importgraph}

À mettre dans la doctring d'un module. Permet de générer un graph sur les imports du module dans un autre module/package/code.

G{callgraph}

À mettre dans la docstring d'une fonction/procédure. Permet de générer un graph des appels passés vers et depuis cette fonction/procédure. Fait appel à un fichier externe (généralement profile.out). D'un usage plus complexe que les autres graphs, il ne sera pas vu dans ce tutoriel.

Concernant l'usage et le bon emploi de cette méthode graphique, je vous renvoie vers la dernière partie, concernant une mise en situation afin de mieux cerner l'utilisation d'Epydoc avec graphique.

II-C-3 - Mise en page de la documentation via CSS

La mise en page de la documentation est assurée par une feuille de style CSS. Le modèle de base est disponible à cette adresse:

http://epydoc.sourceforge.net/stylesheet.html

CSS par defaut d'Epydoc

1. /* Body color */

2. body               { background: #ffffff; color: #000000; }

4. /* Tables */

5. table.summary, table.details, table.index

6. { background: #e8f0f8; color: #000000; }

7. tr.summary, tr.details, tr.index

8. { background: #70b0f0; color: #000000;

9. text-align: left; font-size: 120%; }

11. /* Headings */

12. h1.heading         { font-size: +140%; font-style: italic;

13. font-weight: bold; }

14. h2.heading         { font-size: +125%; font-style: italic;

15. font-weight: bold; }

16. h3.heading         { font-size: +110%; font-style: italic;

17. font-weight: normal; }

19. /* Base tree */

20. pre.base-tree      { font-size: 80%; }

22. /* Details Sections */

23. table.func-details { background: #e8f0f8; color: #000000;

24. border: 2px groove #c0d0d0;

25. padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }

26. h3.func-detail     { background: transparent; color: #000000;

27. margin: 0 0 1em 0; }

29. table.var-details  { background: #e8f0f8; color: #000000;

30. border: 2px groove #c0d0d0;

31. padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }

32. h3.var-details     { background: transparent; color: #000000;

33. margin: 0 0 1em 0; }

35. /* Function signatures */

36. .sig               { background: transparent; color: #000000;

37. font-weight: bold; }

38. .sig-name          { background: transparent; color: #006080; }

39. .sig-arg, .sig-kwarg, .sig-vararg

40. { background: transparent; color: #008060; }

41. .sig-default       { background: transparent; color: #602000; }

42. .summary-sig       { background: transparent; color: #000000; }

43. .summary-sig-name  { background: transparent; font-weight: bold; }

44. .summary-sig-arg, .summary-sig-kwarg, .summary-sig-vararg

45. { background: transparent; color: #008060; }

47. /* Doctest blocks */

48. .pysrc             { background: transparent; color: #000000; }

49. .pyprompt          { background: transparent; color: #003030;

50. font-weight: bold;}

51. .pystring          { background: transparent; color: #006030; }

52. .pycomment         { background: transparent; color: #003060; }

53. .pykeyword         { background: transparent; color: #402000; }

54. .pyoutput          { background: transparent; color: #404040; }

56. /* Navigation bar */

57. table.navbar       { background: #a0c0ff; color: #000000;

58. border: 2px groove #c0d0d0; }

59. th.navbar          { background: #a0c0ff; color: #6090d0; font-size: 110% }

60. th.navselect       { background: #70b0ff; color: #000000; font-size: 110% }

62. /* Links */

63. a:link             { background: transparent; color: #0000ff; }

64. a:visited          { background: transparent; color: #204080; }

65. a.navbar:link      { background: transparent; color: #0000ff;

66. text-decoration: none; }

67. a.navbar:visited   { background: transparent; color: #204080;

68. text-decoration: none; }

L'interface graphique, présentée ci-après, vous laissera le choix de plusieurs styles par défaut.

III - Interface

III-A - Ligne de commande

Le plus basique, mais indispensable dans certains cas. Un outil graphique étant disponible, et plus convivial, nous ne ferons que survoler cette possibilité.

Tout d'abord le prototype de cette ligne de commande :

epydoc [--html|--pdf] [-o DIR] [--parse-only|--introspect-only] [-v|-q]

[--name NAME] [--url URL] [--docformat NAME] [--graph GRAPHTYPE]

[--inheritance STYLE] [--config FILE] OBJECTS...

Comme on peut le constater, cette ligne de commande est relativement simple et possède peu d'options que nous allons maintenant détailler.

--html

Génère une documentation HTML (par defaut)

--pdf

Génère une documentation pdf

-o DIR
--output DIR
--target DIR

Permet de préciser un dossier de sortie pour la documentation

--parse-only
--introspect-only

Deux méthodes sont utilisées par Epydoc pour générer la documentation : la simple lecture des docstrings à même le code source (parse) et l'import du module suivi d'une analyse par introspection (introspect). Par défaut, les deux méthodes combinées sont utilisées. Vous avez ici la possibilité de préciser à Epydoc que vous souhaitez n'en utiliser qu'une seule.

-v
-q

Permet d'améliorer (-v) ou de diminuer (-q) la verbosité d'Epydoc. Comprenez par là que vous pouvez choisir de faire apparaître plus ou moins d'informations au cours de la génération de la documentation : warning, erreur…

--name NAME

Permet de préciser le nom du projet

--url URL

Permet de préciser l'adresse Internet du projet

--docformat NAME

Permet de stipuler à Epydoc le type de formalisme utilisé dans les docstrings. Pour éviter cela on peut utiliser le __docformat__ juste après la docstring du module. Le standard epydoc est :
« epytext ».
ex :
"""
ma docstring
"""
__docformat__ = "restructuredtext en"
[…]

--graph GRAPHTYPE

Permet de demander la génération de graphiques dans la documentation. Trois types de graphiques possibles :
classtree : décrit chaque classe et sous classe ;
callgraph : décrit les fonctions appelées et appelantes ;
umlclass : décrit chaque classe et sous classe au format UML.

--inheritance STYLE

Permet de choisir de quelle façon seront affichées les différentes classes et fonctions qui héritent, rapport à celles qui n'héritent pas. Trois possibilités :
grouped : groupement par classe sous forme de tableau ;
listed : groupement par classe sous forme de listing ;
included : aucune différenciation.

--config FILE

Permet de préciser à Epydoc d'utiliser un fichier de configuration. Il s'agit d'un fichier contenant l'ensemble des paramétrages désirés. Cela permet de standardiser aisément les docs générées, tout en simplifiant la vie de l'utilisateur.

Un exemple simple de fichier de configuration, selon le site d'Epydoc :

1. [epydoc] # Epydoc section marker (required by ConfigParser)

3. # Information about the project.

4. name: My Cool Project

5. url: http://cool.project/

7. # The list of modules to document.  Modules can be named using

8. # dotted names, module filenames, or package directory names.

9. # This option may be repeated.

10. modules: sys, os.path, re

11. modules: my/project/driver.py

13. # Write html output to the directory "apidocs"

14. output: html

15. target: apidocs/

17. # Include all automatically generated graphs.  These graphs are

18. # generated using Graphviz dot.

19. graph: all

20. dotpath: /usr/local/bin/dot

Et un exemple beaucoup plus complet :

1. [epydoc] # Epydoc section marker (required by ConfigParser)

3. # The list of objects to document.  Objects can be named using

4. # dotted names, module filenames, or package directory names.

5. # Alases for this option include "objects" and "values".

6. modules: sys, os.path, re

8. # The type of output that should be generated.  Should be one

9. # of: html, text, latex, dvi, ps, pdf.

10. output: html

12. # The path to the output directory.  May be relative or absolute.

13. target: html/

15. # An integer indicating how verbose epydoc should be.  The default

16. # value is 0; negative values will supress warnings and errors;

17. # positive values will give more verbose output.

18. verbosity: 0

20. # A boolean value indicating that Epydoc should show a tracaback

21. # in case of unexpected error. By default don't show tracebacks

22. debug: 0

24. # If True, don't try to use colors or cursor control when doing

25. # textual output. The default False assumes a rich text prompt

26. simple-term: 0

29. ### Generation options

31. # The default markup language for docstrings, for modules that do

32. # not define __docformat__.  Defaults to epytext.

33. docformat: epytext

35. # Whether or not parsing should be used to examine objects.

36. parse: yes

38. # Whether or not introspection should be used to examine objects.

39. introspect: yes

41. # Don't examine in any way the modules whose dotted name match this

42. # regular expression pattern.

43. #exclude

45. # Don't perform introspection on the modules whose dotted name match

46. # this

47. # regular expression pattern.

48. #exclude-introspect

50. # Don't perform parsing on the modules whose dotted name match this

51. # regular expression pattern.

52. #exclude-parse

54. # The format for showing inheritance objects.

55. # It should be one of: 'grouped', 'listed', 'included'.

56. inheritance: listed

58. # Whether or not to inclue private variables.  (Even if included,

59. # private variables will be hidden by default.)

60. private: yes

62. # Whether or not to list each module's imports.

63. imports: no

65. # Whether or not to include syntax highlighted source code in

66. # the output (HTML only).

67. sourcecode: yes

69. # Whether or not to includea a page with Epydoc log, containing

70. # effective option at the time of generation and the reported logs.

71. include-log: no

74. ### Output options

76. # The documented project's name.

77. #name: Example

79. # The CSS stylesheet for HTML output.  Can be the name of a builtin

80. # stylesheet, or the name of a file.

81. css: white

83. # The documented project's URL.

84. #url: http://some.project/

86. # HTML code for the project link in the navigation bar.  If left

87. # unspecified, the project link will be generated based on the

88. # project's name and URL.

89. #link: <a href="somewhere">My Cool Project</a>

91. # The "top" page for the documentation.  Can be a URL, the name

92. # of a module or class, or one of the special names "trees.html",

93. # "indices.html", or "help.html"

94. #top: os.path

96. # An alternative help file.  The named file should contain the

97. # body of an HTML file; navigation bars will be added to it.

98. #help: my_helpfile.html

100. # Whether or not to include a frames-based table of contents.

101. frames: yes

103. # Whether each class should be listed in its own section when

104. # generating LaTeX or PDF output.

105. separate-classes: no

108. ### API linking options

110. # Define a new API document.  A new interpreted text role

111. # will be created

112. #external-api: epydoc

114. # Use the records in this file to resolve objects in the API named

115. # NAME.

116. #external-api-file: epydoc:api-objects.txt

118. # Use this URL prefix to configure the string returned for external

119. # API.

120. #external-api-root: epydoc:http://epydoc.sourceforge.net/api

123. ### Graph options

125. # The list of graph types that should be automatically included

126. # in the output.  Graphs are generated using the Graphviz "dot"

127. # executable.  Graph types include: "classtree", "callgraph",

128. # "umlclass".  Use "all" to include all graph types

129. graph: all

131. # The path to the Graphviz "dot" executable, used to generate

132. # graphs.

133. dotpath: /usr/local/bin/dot

135. # The name of one or more pstat files (generated by the profile

136. # or hotshot module).  These are used to generate call graphs.

137. pstat: profile.out

139. # Specify the font used to generate Graphviz graphs.

140. # (e.g., helvetica or times).

141. graph-font: Helvetica

143. # Specify the font size used to generate Graphviz graphs.

144. graph-font-size: 10

147. ### Return value options

149. # The condition upon which Epydoc should exit with a non-zero

150. # exit status. Possible values are error, warning, docstring_warning

151. #fail-on: error

Ces fichiers sont lus d'après le module ConfigParser, disponible à cette adresse :

http://docs.python.org/2/library/configparser.html

III-B - GUI

Afin de simplifier la vie des utilisateurs de l'outil, et pour les réfractaires à la ligne de commande, Epydoc dispose d'une interface graphique. Pour l'appeler, il suffit de saisir epydocgui dans un terminal.

Une fenêtre Tkinter apparaîtra alors. Si cette dernière n'est pas du dernier cri en matière d'esthétisme, elle n'en reste pas moins pleinement fonctionnelle.

Illustration: Epydocgui en version complète

Un « clic » sur le texte « option », situé au centre de la fenêtre vous permettra de commuter entre le mode complet (), et le mode simplifié. Dans ce dernier mode, la moitié droite disparaîtra alors. Il s'agit du mode de lancement par défaut.

Cette interface peut être divisée en 5 grandes parties :

- Partie1 : les modules à documenter, en haut à gauche ;

- Partie 2 : la partie génération de documentations, en bas à gauche (à partir du bouton start) ;

- Partie 3 : les options projet : en haut à droite ;

- Partie 4 : la configuration d'aide ;

- Partie 5 : le style de la documentation générée.

Nous aborderons ici chaque partie indépendamment afin d'en expliquer au mieux le fonctionnement.

III-B-1 - Partie 1 : Les modules/packages à documenter

Ici, il suffit de cliquer sur le bouton « BROWSE » afin de choisir son/ses module(s) à documenter.

Vous pouvez documenter un ou plusieurs modules à la fois. Toutefois attention, seule une doc HTML est générée à la fois. Je m'explique : si vous indiquez plusieurs modules à documenter, ils se retrouveront tous dans la même documentation. Si vous n'en indiquez qu'un à la fois, vous aurez autant de documentations que de modules.

C'est donc à vous de jouer à ce niveau en fonction de vos besoins et attentes.

Si une erreur a lieu à l'importation, elle apparaîtra dans la case texte « Messages » de la partie 2.

III-B-2 - Partie 2 : La génération de la documentation

Une fois les modules sélectionnés, sans erreur, et le paramétrage effectué, il suffit de cliquer sur le bouton start.

Si des erreurs empêchent la bonne génération de la documentation, elles apparaîtront dans la case texte « Messages ». Sinon un message de succès y sera affiché.

Sous Linux, par défaut, la documentation est générée dans le Home, dans un dossier « html ».

III-B-3 - Partie 3 : Les options projet

La partie la plus paramétrable. Au début rien de sorcier, vous pouvez renseigner le nom (« Project Name ») ainsi que l'URL (« Project URL ») de votre projet.

« Output Directory » vous permet de préciser le chemin de sortie de votre documentation.

Viennent ensuite trois options cochables au choix :

Generate a frame-based table of contents

Permet de générer un index

Generate documentation for private object

Permet de prendre en compte les objets privés dans la documentation générée

List imported classes and functions

Permet de lister les classes et fonctions importées

Ensuite nous pouvons préciser le type de formalisme utilisé dans les docstrings. Bien entendu, la valeur par défaut est « Epytext ». Je ne détaillerai pas les autres formats qui me semblent superflus. Je vous renvoie donc à la documentation online les concernant.

Viens ensuite le « inheritance style ». Il s'agit de la façon dont les méthodes, variables et propriétés issues de l'héritage seront représentées dans la documentation. Trois possibilités :

Grouped (par defaut)

Les objets sont classés en groupe par classe, selon les classes dont ils héritent

Listed

Les objets sont classés sous forme de listing, en séparant bien les objets qui héritent et ceux qui n'héritent pas

Included

Objets héritants, et objets non héritants sont mélangés sans être distingués les uns des autres

Vous pouvez voir la différence respectivement sur les sites suivants :

http://epydoc.sourceforge.net/examples/grouped/inh_example.Programmer-class.html

http://epydoc.sourceforge.net/examples/listed/inh_example.Programmer-class.html

http://epydoc.sourceforge.net/examples/included/inh_example.Programmer-class.html

Enfin, la section « Get docs from ». Il s'agit de la méthode que va utiliser Epydoc pour générer la documentation. Il y a deux méthodes possibles. Nous avons le choix entre utiliser une seule d'entre elles, ou bien les combiner. Cette dernière façon de procéder est celle qui donne le meilleur résultat. C'est également la méthode par défaut d'Epydoc.

Parsing

Epydoc parcourt le code source afin d'en extraire un maximum d'informations

Introspecting

Epydoc importe chaque module afin de l'analyser d'une autre façon

Je ne peux que vous inviter à essayer les différentes options afin de choisir celle qui convient le mieux.

III-B-4 - Partie 4 : La configuration de l'aide

Cette partie permet de gérer l'aide utilisateur.

En effet, une fois la documentation générée, vous y trouverez un fichier nommé « help.html ». Il s'agit d'un fichier indiquant comment naviguer dans la documentation générée.

Vous avez ici l'opportunité de la modifier en indiquant un fichier à utiliser en lieu et place.

III-B-5 - Partie 5 : Le style de mise en page

Vous pouvez choisir le style qu'aura votre documentation en sortie.

Pour cela, Epydoc vous propose d'utiliser certains styles définis par défaut, ou bien d'indiquer le chemin du style désiré.

Pour créer un style propre à votre société, organisation, ou autre, vous pouvez vous baser sur la feuille css du style par défaut (cf code CSS).

Une fois encore, je ne peux que vous conseiller d'essayer ce qui existe afin de faire votre choix.

IV - Mise en pratique

Pour cette mise en situation, nous allons nous baser sur un cas, très simple et basique, mais suffisamment explicite :

Nous utiliserons Epydocgui, et l'Epytext Sections. Nous demanderons à générer les trois types de graphs qui ont été détaillés plus haut.

Et maintenant, voici le code associé à chacun des fichiers.

__init__.py

1. #!/usr/bin/env python

2. #-*- coding:utf-8 -*

5. """

6. :

8. G{packagetree}

10. G{importgraph Demo}

11. """

Demo.py

1. #!/usr/bin/env python

2. #-*- coding:utf-8 -*

5. """

6. :

8. G{importgraph Demo}

9. """

13. class Tabouret():

14. """

15. Classe pour créer un objet tabouret :

17. G{classtree}

19. DESCRIPTION

20. ===========

21. Permet de créer un objet tabouret

23. PARAMETRES

24. ==========

25. nb

26. --

27. Nombre de pieds du tabouret

29. RETURN

30. ======

31. Retourne un objet tabouret

32. """

35. #===================================================#

36. #                       Init                        #

37. #===================================================#

38. def __init__(self, nb) :

39. """

40. :

44. """

45. self.typ = "Tabouret a %s pieds" % nb

50. #===================================================#

51. #                       Init                        #

52. #===================================================#

53. def affiche(self, txt = "") :

54. """

55. :

57. DESCRIPTION

58. ===========

59. Permet d'afficher un texte passé en paramètre

60. """

61. print txt

66. class Chaise(Tabouret):

67. """

68. Classe pour créer un objet chaise :

70. G{classtree}

72. DESCRIPTION

73. ===========

74. Permet de créer un objet chaise. Une chaise est un tabouret

75. avec un dossier. La classe chaise hérite de la classe Tabouret

77. PARAMETRES

78. ==========

79. nb

80. --

81. Nombre de pieds de la chaise

83. RETURN

84. ======

85. Retourne un objet chaise

87. """

90. #===================================================#

91. #                       Init                        #

92. #===================================================#

93. def __init__(self, nb) :

94. """

95. :

97. Permet de créer un objet chaise

98. """

99. self.typ = "Chaise a %s pieds" % nb

104. class Table():

105. """

106. Classe pour créer un objet table:

108. G{classtree}

110. DESCRIPTION

111. ===========

112. Permet de créer un objet table

114. PARAMETRES

115. ==========

116. nb

117. --

118. Nombre de pieds de la table

120. RETURN

121. ======

122. Retourne un objet table

123. """

126. #===================================================#

127. #                       Init                        #

128. #===================================================#

129. def __init__(self, nb) :

130. self.typ = "Table a %s pieds" % nb

135. #===================================================#

136. #                 Main de la classe                 #

137. #===================================================#

138. if __name__ == '__main__':

139. mon_tabouret = Tabouret(3)

140. ma_chaise = Chaise(4)

141. ma_table = Table(4)

143. print mon_tabouret.typ

144. print ma_chaise.typ

145. print ma_table.typ

Demo2.py

1. #!/usr/bin/env python

2. #-*- coding:utf-8 -*

5. import Demo

7. mon_tabouret = Demo.Tabouret(3)

8. ma_chaise = Demo.Chaise(4)

9. ma_table = Demo.Table(4)

11. print "Ma cusisine comporte :"

12. print "un", mon_tabouret.typ

13. print "trois", ma_chaise.typ

14. print "une", ma_table.typ

16. print""

17. mon_tabouret.affiche("Fin")

IV-A - Génération de la documentation

Epydocgui sera utilisé en mode basique

L'import se passe sans soucis, et la génération de la documentation également. Voici quelques captures d'écran :

V - Conclusion

Ainsi, comme nous avons pu le voir, Epydoc possède une IHM simple d'utilisation, et la documentation générée est très facilement exploitable.

Il s'agit d'un outil fort utile, et qui ne demande rien d'autre que de maintenir à jour ses docstrings, ce que tout bon développeur se respectant fait systématiquement.

Enfin, il est possible d'utiliser son propre style de CSS afin de personnaliser la documentation générée en sortie.

Certes, l'outil est moins puissant que certains de ses « concurrents », surtout en termes de personnalisation, mais sa simplicité d'utilisation compense amplement cette faiblesse.

VI - Remerciements

Merci aux personnes suivantes pour leur aide pour cet article :

- Zoom61 ;

- Phanloga.