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 EpydocEpydoc, 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 |
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 |
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 |
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 |
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 |
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: |
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(): |
|
Rendu final type |
Parameters: |
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
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
/* Body color */
body { background: #ffffff; color: #000000; }
/* Tables */
table.summary, table.details, table.index
{ background: #e8f0f8; color: #000000; }
tr.summary, tr.details, tr.index
{ background: #70b0f0; color: #000000;
text-align: left; font-size: 120%; }
/* Headings */
h1.heading { font-size: +140%; font-style: italic;
font-weight: bold; }
h2.heading { font-size: +125%; font-style: italic;
font-weight: bold; }
h3.heading { font-size: +110%; font-style: italic;
font-weight: normal; }
/* Base tree */
pre.base-tree { font-size: 80%; }
/* Details Sections */
table.func-details { background: #e8f0f8; color: #000000;
border: 2px groove #c0d0d0;
padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }
h3.func-detail { background: transparent; color: #000000;
margin: 0 0 1em 0; }
table.var-details { background: #e8f0f8; color: #000000;
border: 2px groove #c0d0d0;
padding: 0 1em 0 1em; margin: 0.4em 0 0 0; }
h3.var-details { background: transparent; color: #000000;
margin: 0 0 1em 0; }
/* Function signatures */
.sig { background: transparent; color: #000000;
font-weight: bold; }
.sig-name { background: transparent; color: #006080; }
.sig-arg, .sig-kwarg, .sig-vararg
{ background: transparent; color: #008060; }
.sig-default { background: transparent; color: #602000; }
.summary-sig { background: transparent; color: #000000; }
.summary-sig-name { background: transparent; font-weight: bold; }
.summary-sig-arg, .summary-sig-kwarg, .summary-sig-vararg
{ background: transparent; color: #008060; }
/* Doctest blocks */
.pysrc { background: transparent; color: #000000; }
.pyprompt { background: transparent; color: #003030;
font-weight: bold;}
.pystring { background: transparent; color: #006030; }
.pycomment { background: transparent; color: #003060; }
.pykeyword { background: transparent; color: #402000; }
.pyoutput { background: transparent; color: #404040; }
/* Navigation bar */
table.navbar { background: #a0c0ff; color: #000000;
border: 2px groove #c0d0d0; }
th.navbar { background: #a0c0ff; color: #6090d0; font-size: 110% }
th.navselect { background: #70b0ff; color: #000000; font-size: 110% }
/* Links */
a:link { background: transparent; color: #0000ff; }
a:visited { background: transparent; color: #204080; }
a.navbar:link { background: transparent; color: #0000ff;
text-decoration: none; }
a.navbar:visited { background: transparent; color: #204080;
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) |
|
|
Génère une documentation pdf |
|
-o
DIR
|
Permet de préciser un dossier de sortie pour la documentation |
|
--parse-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
|
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 : |
|
--graph GRAPHTYPE |
Permet de demander la génération de graphiques dans la documentation. Trois types de graphiques possibles : |
|
--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 : |
|
--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 :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
[epydoc] # Epydoc section marker (required by ConfigParser)
# Information about the project.
name: My Cool Project
url: http://cool.project/
# The list of modules to document. Modules can be named using
# dotted names, module filenames, or package directory names.
# This option may be repeated.
modules: sys, os.path, re
modules: my/project/driver.py
# Write html output to the directory "apidocs"
output: html
target: apidocs/
# Include all automatically generated graphs. These graphs are
# generated using Graphviz dot.
graph: all
dotpath: /usr/local/bin/dot
Et un exemple beaucoup plus complet :
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
142.
143.
144.
145.
146.
147.
148.
149.
150.
151.
[epydoc] # Epydoc section marker (required by ConfigParser)
# The list of objects to document. Objects can be named using
# dotted names, module filenames, or package directory names.
# Alases for this option include "objects" and "values".
modules: sys, os.path, re
# The type of output that should be generated. Should be one
# of: html, text, latex, dvi, ps, pdf.
output: html
# The path to the output directory. May be relative or absolute.
target: html/
# An integer indicating how verbose epydoc should be. The default
# value is 0; negative values will supress warnings and errors;
# positive values will give more verbose output.
verbosity: 0
# A boolean value indicating that Epydoc should show a tracaback
# in case of unexpected error. By default don't show tracebacks
debug: 0
# If True, don't try to use colors or cursor control when doing
# textual output. The default False assumes a rich text prompt
simple-term: 0
### Generation options
# The default markup language for docstrings, for modules that do
# not define __docformat__. Defaults to epytext.
docformat: epytext
# Whether or not parsing should be used to examine objects.
parse: yes
# Whether or not introspection should be used to examine objects.
introspect: yes
# Don't examine in any way the modules whose dotted name match this
# regular expression pattern.
#exclude
# Don't perform introspection on the modules whose dotted name match
# this
# regular expression pattern.
#exclude-introspect
# Don't perform parsing on the modules whose dotted name match this
# regular expression pattern.
#exclude-parse
# The format for showing inheritance objects.
# It should be one of: 'grouped', 'listed', 'included'.
inheritance: listed
# Whether or not to inclue private variables. (Even if included,
# private variables will be hidden by default.)
private: yes
# Whether or not to list each module's imports.
imports: no
# Whether or not to include syntax highlighted source code in
# the output (HTML only).
sourcecode: yes
# Whether or not to includea a page with Epydoc log, containing
# effective option at the time of generation and the reported logs.
include-log: no
### Output options
# The documented project's name.
#name: Example
# The CSS stylesheet for HTML output. Can be the name of a builtin
# stylesheet, or the name of a file.
css: white
# The documented project's URL.
#url: http://some.project/
# HTML code for the project link in the navigation bar. If left
# unspecified, the project link will be generated based on the
# project's name and URL.
#link: <a href="somewhere">My Cool Project</a>
# The "top" page for the documentation. Can be a URL, the name
# of a module or class, or one of the special names "trees.html",
# "indices.html", or "help.html"
#top: os.path
# An alternative help file. The named file should contain the
# body of an HTML file; navigation bars will be added to it.
#help: my_helpfile.html
# Whether or not to include a frames-based table of contents.
frames: yes
# Whether each class should be listed in its own section when
# generating LaTeX or PDF output.
separate-classes: no
### API linking options
# Define a new API document. A new interpreted text role
# will be created
#external-api: epydoc
# Use the records in this file to resolve objects in the API named
# NAME.
#external-api-file: epydoc:api-objects.txt
# Use this URL prefix to configure the string returned for external
# API.
#external-api-root: epydoc:http://epydoc.sourceforge.net/api
### Graph options
# The list of graph types that should be automatically included
# in the output. Graphs are generated using the Graphviz "dot"
# executable. Graph types include: "classtree", "callgraph",
# "umlclass". Use "all" to include all graph types
graph: all
# The path to the Graphviz "dot" executable, used to generate
# graphs.
dotpath: /usr/local/bin/dot
# The name of one or more pstat files (generated by the profile
# or hotshot module). These are used to generate call graphs.
pstat: profile.out
# Specify the font used to generate Graphviz graphs.
# (e.g., helvetica or times).
graph-font: Helvetica
# Specify the font size used to generate Graphviz graphs.
graph-font-size: 10
### Return value options
# The condition upon which Epydoc should exit with a non-zero
# exit status. Possible values are error, warning, docstring_warning
#fail-on: error
Ces fichiers sont lus d'après le module ConfigParser, disponible à cette adresse :
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.
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.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
#!/usr/bin/env python
#-*- coding:utf-8 -*
"""
:
G{packagetree}
G{importgraph Demo}
"""
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
142.
143.
144.
145.
#!/usr/bin/env python
#-*- coding:utf-8 -*
"""
:
G{importgraph Demo}
"""
class Tabouret():
"""
Classe pour créer un objet tabouret :
G{classtree}
DESCRIPTION
===========
Permet de créer un objet tabouret
PARAMETRES
==========
nb
--
Nombre de pieds du tabouret
RETURN
======
Retourne un objet tabouret
"""
#===================================================#
# Init #
#===================================================#
def __init__(self, nb) :
"""
:
"""
self.typ = "Tabouret a %s pieds" % nb
#===================================================#
# Init #
#===================================================#
def affiche(self, txt = "") :
"""
:
DESCRIPTION
===========
Permet d'afficher un texte passé en paramètre
"""
print txt
class Chaise(Tabouret):
"""
Classe pour créer un objet chaise :
G{classtree}
DESCRIPTION
===========
Permet de créer un objet chaise. Une chaise est un tabouret
avec un dossier. La classe chaise hérite de la classe Tabouret
PARAMETRES
==========
nb
--
Nombre de pieds de la chaise
RETURN
======
Retourne un objet chaise
"""
#===================================================#
# Init #
#===================================================#
def __init__(self, nb) :
"""
:
Permet de créer un objet chaise
"""
self.typ = "Chaise a %s pieds" % nb
class Table():
"""
Classe pour créer un objet table:
G{classtree}
DESCRIPTION
===========
Permet de créer un objet table
PARAMETRES
==========
nb
--
Nombre de pieds de la table
RETURN
======
Retourne un objet table
"""
#===================================================#
# Init #
#===================================================#
def __init__(self, nb) :
self.typ = "Table a %s pieds" % nb
#===================================================#
# Main de la classe #
#===================================================#
if __name__ == '__main__':
mon_tabouret = Tabouret(3)
ma_chaise = Chaise(4)
ma_table = Table(4)
print mon_tabouret.typ
print ma_chaise.typ
print ma_table.typ
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
#!/usr/bin/env python
#-*- coding:utf-8 -*
import Demo
mon_tabouret = Demo.Tabouret(3)
ma_chaise = Demo.Chaise(4)
ma_table = Demo.Table(4)
print "Ma cusisine comporte :"
print "un", mon_tabouret.typ
print "trois", ma_chaise.typ
print "une", ma_table.typ
print""
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.
