Production (automatique) de documentations
F. Langrognet
F. Langrognet ()Production (automatique) de documentations Octobre 2013 1 / 69
PLAN
1 Introduction2 Comment ça marche ?
Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...F. Langrognet ()Production (automatique) de documentations Octobre 2013 2 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 3 / 69
Introduction
ObjectifGénérer automatiquement (ou presque...) des documentations
techniques (pour les développeurs)
pour les utilisateurs ?
Historique1995-1997 : 1ers outils de génération :
javadoc, ROBODoc (1995)
Doxygen (1997)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 4 / 69
Quelles documentations ? (1)
Documentation logicielle (pour les développeurs)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 5 / 69
Exemples
javadocJava SDK
F. Langrognet ()Production (automatique) de documentations Octobre 2013 6 / 69
ExemplesjavadocNetBeans
F. Langrognet ()Production (automatique) de documentations Octobre 2013 7 / 69
ExemplesDoxygen
KDE
F. Langrognet ()Production (automatique) de documentations Octobre 2013 8 / 69
Quelles documentations ? (2)Documentation pour l’utilisateur final
Quelques motivations :
Documentation intégrée dans le processus de développementLe système de gestion de version peut/doit servir aussi pour les documentations !
Profiter des fonctionnalités de l’outil de production de documentationI Formats de sortieI Mise en pageI Description des algorithmes, des formules
F. Langrognet ()Production (automatique) de documentations Octobre 2013 9 / 69
Caractéristiques - Fonctionnalités
CaractéristiquesFormats d’entréeCode source (texte)
Binaire
Formats de sortie
HTML
Latex
ps
XML
man pages
RTF
DocBook
Fonctionnalités
Description des classes, des fonctions
Diagrammes (classes, appels, . . . )
Possibilité d’étendre à d’autres langages
Personnalisation des sorties
Mise en page, contenu :I Possibilité d’insérer des balises HTMLI Possibilité d’insérer du code Latex (formules
mathématiques, ...)I Facilité pour la mise en page
F. Langrognet ()Production (automatique) de documentations Octobre 2013 10 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 11 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 12 / 69
Sur quels types de fichiers ?
Fichiers binairesDocumentation générée à partir des binaires seulement
Exemple : classDoc pour java
Fichiers sourcesDocumentation générée à partir du code source en utilisant
La grammaire, les mots clés du langageOn peut donc générer des documentations sans travail spécifique
Des commentaires, des balises spécifiquesPour enrichir la documentation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 13 / 69
Documentation produite sans commentaire spécifiqueni balise
Date.h Documentation générée (html)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 14 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 15 / 69
Pour quelles sorties ?
Quelles informations ?Description des fonctions (paramètres, type de retour, . . . )
Description des classes
Description des fichiers
Graphes d’appels
Diagrammes (de classses, de collaboration, . . .)
Liens vers les fichiers sources
. . .
Format des fichiers de sortieDifférents formats (en fonction des possibilités de l’outil) :
html, pdf, latex, ps, XML, . . .
Personnalisation possible des sorties
F. Langrognet ()Production (automatique) de documentations Octobre 2013 16 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 17 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 18 / 69
Doxygen - Fiche d’identitéAuteur : Dimitri Van Heesch
licence : GNU GPL
1re version : 1997
OS : BSD, Linux, Mac OS, Unix, Windows
Entrée : code source
Sorties : HTML, LATEX, Man Pages, RTF, XML, Qt Help Project, PDF, PS, . . .
Nombreuses possibilités de personnalisation
Documentation KDE
F. Langrognet ()Production (automatique) de documentations Octobre 2013 19 / 69
Pour quels langages ?
Langages
+ Possibilités d’extension pour d’autres langages non natifs
F. Langrognet ()Production (automatique) de documentations Octobre 2013 20 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 21 / 69
Flux de donnéesSchéma général
F. Langrognet ()Production (automatique) de documentations Octobre 2013 22 / 69
Fichiers sources
Seuls les fichiers sources sont indispensables
F. Langrognet ()Production (automatique) de documentations Octobre 2013 23 / 69
Fichier de config
Pour définir/conserver les préférences, les options, ...
DoxyWizard permet de gérer ce fichier de configurationF. Langrognet ()Production (automatique) de documentations Octobre 2013 24 / 69
Personnalisation des sorties
Fichiers utilisés pour la personnalisation des sorties
F. Langrognet ()Production (automatique) de documentations Octobre 2013 25 / 69
Documentations tierces
Pour insérer des documentations d’autres composants
F. Langrognet ()Production (automatique) de documentations Octobre 2013 26 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 27 / 69
Comment utilise t-on Doxygen ?1. En ligne de commande
Uniquement avec les fichiers sourcesuser$ doxygen *.h
En utilisant la configuration et des options de sortie par défaut
En utilisant un fichier de configuration
Créer un fichier de configurationuser$ doxygen -g my_config.txt
Utiliser un fichier de configurationuser$ doxygen my_config.txt
F. Langrognet ()Production (automatique) de documentations Octobre 2013 28 / 69
Comment utilise t-on Doxygen ?2. Avec un outil graphique (1)
DoxyWizard
F. Langrognet ()Production (automatique) de documentations Octobre 2013 29 / 69
Comment utilise t-on Doxygen ?2. Avec un outil graphique (2)
DoxyWizardPour configurer et lancer doxygen
ConfigurationFormats de sorties Types de sorties
F. Langrognet ()Production (automatique) de documentations Octobre 2013 30 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 31 / 69
Rappel ...Documentation produite sans commentaire spécifique ni balise
user$ doxygen Date.h
Date.h Documentation générée (html)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 32 / 69
Informations Doxygen
Et Commentaires interprétablesInformations pour Doxygen dans des commentaires interprétables parDoxygen
En C/C++ :
Style C avec avec deux */*** Documentation pour doxygen*/
Style C avec avec un !/* !* Documentation pour doxygen*/
Style C++ avec avec trois /////// Documentation pour doxygen///
Style C++ avec avec un !// !// !Documentation pour doxygen// !
F. Langrognet ()Production (automatique) de documentations Octobre 2013 33 / 69
Balises
BalisesA placer à l’intérieur des commentaires interprétables par Doxygen.
\fileDescription d’un fichier source ou d’en-tête
\briefDescription courte (peut être complétée par un lien vers
la description détaillée)
\authorAuteur(s)
\versionVersion
\dateDate
\paramDescription de paramètre(s) d’une fonction (/méthode)
\returnDescription de la valeur retournée
\bugDescription d’un bug
\deprecatedDescription d’une partie de code obsolète
\classDescription d’une classe
F. Langrognet ()Production (automatique) de documentations Octobre 2013 34 / 69
Doxygen - Exemples
Informations sur les fichiers d’en-tête
F. Langrognet ()Production (automatique) de documentations Octobre 2013 35 / 69
Informations d’en-tête (1)
Sans balise doxygen
Avec balises d’en-têtedoxygen
F. Langrognet ()Production (automatique) de documentations Octobre 2013 36 / 69
Informations d’en-tête (2)Balises d’en-tête
F. Langrognet ()Production (automatique) de documentations Octobre 2013 37 / 69
Doxygen - Exemples
Description courte / détaillée
F. Langrognet ()Production (automatique) de documentations Octobre 2013 38 / 69
Description courte / détaillée (1)Description courte / détaillée
On peut avoir :
une description courte (\brief)
une description détaillée (sans balise)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 39 / 69
Description courte / détaillée (2)Description courte / détaillée
On peut aussi générer automatiquement la description courte à partir de la description détaillée(option JAVADOC_AUTOBRIEF à YES).La description courte s’arrête au 1er point trouvé dans la description détaillée.
F. Langrognet ()Production (automatique) de documentations Octobre 2013 40 / 69
Doxygen - Exemples
Description d’une méthode / fonction
F. Langrognet ()Production (automatique) de documentations Octobre 2013 41 / 69
Description d’une méthode / fonction (1)Description d’une méthode
Utilsation de \param et \return.
F. Langrognet ()Production (automatique) de documentations Octobre 2013 42 / 69
Description d’une méthode / fonction (2)Balises pour une méthode / fonction
F. Langrognet ()Production (automatique) de documentations Octobre 2013 43 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 44 / 69
Diagrammes (1)
Fonctionnement par défautHiérarchie de classes
F. Langrognet ()Production (automatique) de documentations Octobre 2013 45 / 69
Diagrammes (2)Personnalisation
Avec le logiciel graphviz (et l’option HAVE_DOT=YES)
Hiérarchie de classes
Diagramme de collaboration
F. Langrognet ()Production (automatique) de documentations Octobre 2013 46 / 69
Diagrammes (3)Autres exemples
Diagramme de classe Diagramme de collaboration
F. Langrognet ()Production (automatique) de documentations Octobre 2013 47 / 69
Graphes d’appels
Graphes d’appels (et l’option CALL_GRAPH=YES)
Graphes d’appelants (et l’option CALLER_GRAPH=YES)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 48 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 49 / 69
Personnalisation des sorties
3 niveaux de personnalisation
Avec les fichiers de configuration (modifications mineures)
Avec le fichier de Layout
Avec XML (pour une personnalisation totale)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 50 / 69
Personnalisation des sorties1. Avec les fichiers de configuration (1)
Fichier de configuation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 51 / 69
Personnalisation des sorties1. Avec les fichiers de configuration (2)
Exemples
Couleurs
I HTML_COLORSTYLE_HUEI HTML_COLORSTYLE_SATI HTML_COLORSTYLE_GAMMA
Note : peut être msie à jour via DoxyWizard
Navigation
I DISABLE_INDEX (=NO par défaut)I GENERATE_TREEVIEW (=NO par défaut)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 52 / 69
Personnalisation des sorties1. Avec les fichiers de configuration (3)
Couleurs
Par défaut Personnalisation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 53 / 69
Personnalisation des sorties1. Avec les fichiers de configuration (4)
Navigation
Par défaut Personnalisation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 54 / 69
Personnalisation des sorties1. Avec les fichiers de configuration (5)
Feuille de style, en-tête pied de page
F. Langrognet ()Production (automatique) de documentations Octobre 2013 55 / 69
Personnalisation des sorties1. Avec les fichiers de configuration (6)
Créer les 3 fichiers et les modifieruser$ doxygen -w html header.html footer.html customdoxygen.css
Feuille de style En-tête
Pied de page
Les référencer dans le fichier de configurationHTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_STYLESHEET = customdoxygen.css
F. Langrognet ()Production (automatique) de documentations Octobre 2013 56 / 69
Personnalisation des sorties2. Modification de la structure avec le fichier layout (1)
Fichier de configuation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 57 / 69
Personnalisation des sorties2. Modification de la structure avec le fichier layout (2)
LayoutCréer un fichier layout et le modifier
user$ doxygen -l
Référencer ce fichier layout dans lefichier de configuration(LAYOUT_FILE = DoxygenLayout.xml) :
Execution de doxygenuser$ doxygen configWithLayout.txt
DoxygenLayout.xml
F. Langrognet ()Production (automatique) de documentations Octobre 2013 58 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 59 / 69
Enrichir la documentationQuelques outils
Utilisation de balises Doxygen spécifiques à la mise en page (listes, ....)
Insertion de balises HTML
Utilisation de Latex (pour les formules par exemple)
Motivations pour utiliser Doxygen pour gérer les documentations scientifiqueset/ou pour utilisateurs
Guide utilisateur Doxygen produit par ... Doxygen
F. Langrognet ()Production (automatique) de documentations Octobre 2013 60 / 69
Enrichir la documentation (2)
Exemple avec une formule
F. Langrognet ()Production (automatique) de documentations Octobre 2013 61 / 69
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéFlux de donnéesComment utiliser Doxygen ?BalisesDiagrammes et graphesPersonnalisation des sortiesEnrichir la documentation
4 Pour aller plus loin ...
F. Langrognet ()Production (automatique) de documentations Octobre 2013 62 / 69
Quel outil de génération de documentation choisir ?en.wikipedia.org/wiki/Comparison_of_documentation_generators
Quel langage ?
F. Langrognet ()Production (automatique) de documentations Octobre 2013 63 / 69
Quel outil de génération de documentation choisir ?
Quel langage ? ... suite
F. Langrognet ()Production (automatique) de documentations Octobre 2013 64 / 69
Quel outil de génération de documentation choisir ?
Quel type de fichier en entrée ? ?
F. Langrognet ()Production (automatique) de documentations Octobre 2013 65 / 69
Quel outil de génération de documentation choisir ?
Quel OS ?
F. Langrognet ()Production (automatique) de documentations Octobre 2013 66 / 69
Quel outil de génération de documentation choisir ?
Format de sortie
F. Langrognet ()Production (automatique) de documentations Octobre 2013 67 / 69
RéférencesQuelques références
Comparaison des outils de génération de documentation :en.wikipedia.org/wiki/Comparison_of_documentation_generators
Doxygen :
I Doxygen (officiel) :www.doxygen.org <-> www.stack.nl/ dimitri/doxygen/
I Manuel d’utilisation Doxygen :www.stack.nl/ dimitri/doxygen/manual.html
I Wikipedia :fr.wikipedia.org/wiki/Doxygen
I Initiation à Doxygen pour le C++ :franckh.developpez.com/tutoriels/outils/doxygen/
javadoc
I officiel :http ://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html
I Wikipedia :fr.wikipedia.org/wiki/Javadoc
F. Langrognet ()Production (automatique) de documentations Octobre 2013 68 / 69
Production (automatique) de documentations
FIN
Merci de votre attention
Florent Langrognet
F. Langrognet ()Production (automatique) de documentations Octobre 2013 69 / 69