Production (automatique) de documentations
Transcript of Production (automatique) de documentations
![Page 1: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/1.jpg)
Production (automatique) de documentations
F. Langrognet
F. Langrognet ()Production (automatique) de documentations Octobre 2013 1 / 69
![Page 2: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/2.jpg)
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
![Page 3: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/3.jpg)
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
![Page 4: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/4.jpg)
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
![Page 5: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/5.jpg)
Quelles documentations ? (1)
Documentation logicielle (pour les développeurs)
F. Langrognet ()Production (automatique) de documentations Octobre 2013 5 / 69
![Page 6: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/6.jpg)
Exemples
javadocJava SDK
F. Langrognet ()Production (automatique) de documentations Octobre 2013 6 / 69
![Page 7: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/7.jpg)
ExemplesjavadocNetBeans
F. Langrognet ()Production (automatique) de documentations Octobre 2013 7 / 69
![Page 8: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/8.jpg)
ExemplesDoxygen
KDE
F. Langrognet ()Production (automatique) de documentations Octobre 2013 8 / 69
![Page 9: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/9.jpg)
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
![Page 10: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/10.jpg)
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
![Page 11: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/11.jpg)
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
![Page 12: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/12.jpg)
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
![Page 13: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/13.jpg)
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
![Page 14: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/14.jpg)
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
![Page 15: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/15.jpg)
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
![Page 16: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/16.jpg)
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
![Page 17: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/17.jpg)
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
![Page 18: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/18.jpg)
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
![Page 19: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/19.jpg)
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
![Page 20: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/20.jpg)
Pour quels langages ?
Langages
+ Possibilités d’extension pour d’autres langages non natifs
F. Langrognet ()Production (automatique) de documentations Octobre 2013 20 / 69
![Page 21: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/21.jpg)
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
![Page 22: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/22.jpg)
Flux de donnéesSchéma général
F. Langrognet ()Production (automatique) de documentations Octobre 2013 22 / 69
![Page 23: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/23.jpg)
Fichiers sources
Seuls les fichiers sources sont indispensables
F. Langrognet ()Production (automatique) de documentations Octobre 2013 23 / 69
![Page 24: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/24.jpg)
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
![Page 25: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/25.jpg)
Personnalisation des sorties
Fichiers utilisés pour la personnalisation des sorties
F. Langrognet ()Production (automatique) de documentations Octobre 2013 25 / 69
![Page 26: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/26.jpg)
Documentations tierces
Pour insérer des documentations d’autres composants
F. Langrognet ()Production (automatique) de documentations Octobre 2013 26 / 69
![Page 27: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/27.jpg)
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
![Page 28: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/28.jpg)
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
![Page 29: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/29.jpg)
Comment utilise t-on Doxygen ?2. Avec un outil graphique (1)
DoxyWizard
F. Langrognet ()Production (automatique) de documentations Octobre 2013 29 / 69
![Page 30: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/30.jpg)
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
![Page 31: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/31.jpg)
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
![Page 32: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/32.jpg)
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
![Page 33: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/33.jpg)
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
![Page 34: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/34.jpg)
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
![Page 35: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/35.jpg)
Doxygen - Exemples
Informations sur les fichiers d’en-tête
F. Langrognet ()Production (automatique) de documentations Octobre 2013 35 / 69
![Page 36: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/36.jpg)
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
![Page 37: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/37.jpg)
Informations d’en-tête (2)Balises d’en-tête
F. Langrognet ()Production (automatique) de documentations Octobre 2013 37 / 69
![Page 38: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/38.jpg)
Doxygen - Exemples
Description courte / détaillée
F. Langrognet ()Production (automatique) de documentations Octobre 2013 38 / 69
![Page 39: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/39.jpg)
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
![Page 40: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/40.jpg)
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
![Page 41: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/41.jpg)
Doxygen - Exemples
Description d’une méthode / fonction
F. Langrognet ()Production (automatique) de documentations Octobre 2013 41 / 69
![Page 42: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/42.jpg)
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
![Page 43: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/43.jpg)
Description d’une méthode / fonction (2)Balises pour une méthode / fonction
F. Langrognet ()Production (automatique) de documentations Octobre 2013 43 / 69
![Page 44: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/44.jpg)
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
![Page 45: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/45.jpg)
Diagrammes (1)
Fonctionnement par défautHiérarchie de classes
F. Langrognet ()Production (automatique) de documentations Octobre 2013 45 / 69
![Page 46: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/46.jpg)
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
![Page 47: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/47.jpg)
Diagrammes (3)Autres exemples
Diagramme de classe Diagramme de collaboration
F. Langrognet ()Production (automatique) de documentations Octobre 2013 47 / 69
![Page 48: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/48.jpg)
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
![Page 49: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/49.jpg)
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
![Page 50: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/50.jpg)
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
![Page 51: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/51.jpg)
Personnalisation des sorties1. Avec les fichiers de configuration (1)
Fichier de configuation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 51 / 69
![Page 52: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/52.jpg)
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
![Page 53: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/53.jpg)
Personnalisation des sorties1. Avec les fichiers de configuration (3)
Couleurs
Par défaut Personnalisation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 53 / 69
![Page 54: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/54.jpg)
Personnalisation des sorties1. Avec les fichiers de configuration (4)
Navigation
Par défaut Personnalisation
F. Langrognet ()Production (automatique) de documentations Octobre 2013 54 / 69
![Page 55: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/55.jpg)
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
![Page 56: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/56.jpg)
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
![Page 57: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/57.jpg)
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
![Page 58: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/58.jpg)
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
![Page 59: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/59.jpg)
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
![Page 60: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/60.jpg)
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
![Page 61: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/61.jpg)
Enrichir la documentation (2)
Exemple avec une formule
F. Langrognet ()Production (automatique) de documentations Octobre 2013 61 / 69
![Page 62: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/62.jpg)
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
![Page 63: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/63.jpg)
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
![Page 64: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/64.jpg)
Quel outil de génération de documentation choisir ?
Quel langage ? ... suite
F. Langrognet ()Production (automatique) de documentations Octobre 2013 64 / 69
![Page 65: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/65.jpg)
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
![Page 66: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/66.jpg)
Quel outil de génération de documentation choisir ?
Quel OS ?
F. Langrognet ()Production (automatique) de documentations Octobre 2013 66 / 69
![Page 67: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/67.jpg)
Quel outil de génération de documentation choisir ?
Format de sortie
F. Langrognet ()Production (automatique) de documentations Octobre 2013 67 / 69
![Page 68: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/68.jpg)
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
![Page 69: Production (automatique) de documentations](https://reader031.fdocument.pub/reader031/viewer/2022012300/61e1723e588c426f9f0d85eb/html5/thumbnails/69.jpg)
Production (automatique) de documentations
FIN
Merci de votre attention
Florent Langrognet
F. Langrognet ()Production (automatique) de documentations Octobre 2013 69 / 69