1
Download Production (automatique) de documentations
Transcript
Production (automatique) de documentations F. Langrognet F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 1 / 69 PLAN 1 2 3 4 Introduction Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 2 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 3 / 69 Introduction Objectif Générer automatiquement (ou presque...) des documentations techniques (pour les développeurs) pour les utilisateurs ? Historique 1995-1997 : 1ers outils de génération : javadoc, ROBODoc (1995) Doxygen (1997) F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 4 / 69 Quelles documentations ? (1) Documentation logicielle (pour les développeurs) F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 5 / 69 Exemples javadoc Java SDK F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 6 / 69 Exemples javadoc NetBeans F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 7 / 69 Exemples Doxygen KDE F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 8 / 69 Quelles documentations ? (2) Documentation pour l’utilisateur final Quelques motivations : Documentation intégrée dans le processus de développement Le système de gestion de version peut/doit servir aussi pour les documentations ! Profiter des fonctionnalités de l’outil de production de documentation ◮ ◮ ◮ Formats de sortie Mise en page Description des algorithmes, des formules F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 9 / 69 Caractéristiques - Fonctionnalités Caractéristiques Formats d’entrée Code source (texte) Binaire Fonctionnalités Description des classes, des fonctions Formats de sortie Diagrammes (classes, appels, . . . ) HTML Possibilité d’étendre à d’autres langages PDF Latex ps Personnalisation des sorties Mise en page, contenu : ◮ XML ◮ man pages ◮ Possibilité d’insérer des balises HTML Possibilité d’insérer du code Latex (formules mathématiques, ...) Facilité pour la mise en page RTF DocBook F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 10 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 11 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 12 / 69 Sur quels types de fichiers ? Fichiers binaires Documentation générée à partir des binaires seulement Exemple : classDoc pour java Fichiers sources Documentation générée à partir du code source en utilisant La grammaire, les mots clés du langage On peut donc générer des documentations sans travail spécifique Des commentaires, des balises spécifiques Pour enrichir la documentation F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 13 / 69 Documentation produite sans commentaire spécifique ni balise Date.h F. Langrognet Documentation générée (html) Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 14 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 sortie Diffé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 - ENVOL 2012 Janvier 2013 16 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 17 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 19 / 69 Pour quels langages ? Langages + Possibilités d’extension pour d’autres langages non natifs F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 20 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 21 / 69 Flux de données Schéma général F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 22 / 69 Fichiers sources Seuls les fichiers sources sont indispensables F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 23 / 69 Fichier de config Pour définir/conserver les préférences, les options, ... DoxyWizard permet de gérer ce fichier de configuration F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 24 / 69 Personnalisation des sorties Fichiers utilisés pour la personnalisation des sorties F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 25 / 69 Documentations tierces Pour insérer des documentations d’autres composants F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 26 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 27 / 69 Comment utilise t-on Doxygen ? 1. En ligne de commande Uniquement avec les fichiers sources user$ 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 configuration user$ doxygen -g my_config.txt Utiliser un fichier de configuration user$ doxygen my_config.txt F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 28 / 69 Comment utilise t-on Doxygen ? 2. Avec un outil graphique (1) DoxyWizard F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 29 / 69 Comment utilise t-on Doxygen ? 2. Avec un outil graphique (2) DoxyWizard Pour configurer et lancer doxygen Configuration Formats de sorties F. Langrognet Types de sorties Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 30 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 31 / 69 Rappel ... Documentation produite sans commentaire spécifique ni balise user$ doxygen Date.h Date.h F. Langrognet Documentation générée (html) Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 32 / 69 Informations Doxygen Et Commentaires interprétables Informations pour Doxygen dans des commentaires interprétables par Doxygen En C/C++ : Style C avec avec deux * /** * Documentation pour doxygen */ Style C++ avec avec trois / /// /// Documentation pour doxygen /// Style C avec avec un ! /* ! * Documentation pour doxygen */ Style C++ avec avec un ! // ! // !Documentation pour doxygen // ! F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 33 / 69 Balises Balises A placer à l’intérieur des commentaires interprétables par Doxygen. \file Description d’un fichier source ou d’en-tête \brief Description courte (peut être complétée par un lien vers la description détaillée) \author Auteur(s) \version Version \date Date F. Langrognet \param Description de paramètre(s) d’une fonction (/méthode) \return Description de la valeur retournée \bug Description d’un bug \deprecated Description d’une partie de code obsolète \class Description d’une classe Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 34 / 69 Doxygen - Exemples Informations sur les fichiers d’en-tête F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 35 / 69 Informations d’en-tête (1) Sans balise doxygen F. Langrognet Avec balises d’en-tête doxygen Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 36 / 69 Informations d’en-tête (2) Balises d’en-tête F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 37 / 69 Doxygen - Exemples Description courte / détaillée F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 40 / 69 Doxygen - Exemples Description d’une méthode / fonction F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 42 / 69 Description d’une méthode / fonction (2) Balises pour une méthode / fonction F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 43 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 44 / 69 Diagrammes (1) Fonctionnement par défaut Hiérarchie de classes F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 46 / 69 Diagrammes (3) Autres exemples Diagramme de classe F. Langrognet Diagramme de collaboration Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 48 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 50 / 69 Personnalisation des sorties 1. Avec les fichiers de configuration (1) Fichier de configuation F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 51 / 69 Personnalisation des sorties 1. Avec les fichiers de configuration (2) Exemples Couleurs ◮ ◮ ◮ HTML_COLORSTYLE_HUE HTML_COLORSTYLE_SAT HTML_COLORSTYLE_GAMMA Note : peut être msie à jour via DoxyWizard Navigation ◮ ◮ DISABLE_INDEX (=NO par défaut) GENERATE_TREEVIEW (=NO par défaut) F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 52 / 69 Personnalisation des sorties 1. Avec les fichiers de configuration (3) Couleurs Par défaut F. Langrognet Personnalisation Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 53 / 69 Personnalisation des sorties 1. Avec les fichiers de configuration (4) Navigation Par défaut F. Langrognet Personnalisation Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 54 / 69 Personnalisation des sorties 1. Avec les fichiers de configuration (5) Feuille de style, en-tête pied de page F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 55 / 69 Personnalisation des sorties 1. Avec les fichiers de configuration (6) Créer les 3 fichiers et les modifier user$ doxygen -w html header.html footer.html customdoxygen.css En-tête Feuille de style Pied de page Les référencer dans le fichier de configuration HTML_HEADER = header.html HTML_FOOTER = footer.html HTML_STYLESHEET = customdoxygen.css F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 56 / 69 Personnalisation des sorties 2. Modification de la structure avec le fichier layout (1) Fichier de configuation F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 57 / 69 Personnalisation des sorties 2. Modification de la structure avec le fichier layout (2) Layout Créer un fichier layout et le modifier user$ doxygen -l Référencer ce fichier layout dans le fichier de configuration (LAYOUT_FILE = DoxygenLayout.xml) : DoxygenLayout.xml Execution de doxygen user$ doxygen configWithLayout.txt F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 58 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 59 / 69 Enrichir la documentation Quelques 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 scientifiques et/ou pour utilisateurs Guide utilisateur Doxygen produit par ... Doxygen F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 60 / 69 Enrichir la documentation (2) Exemple avec une formule F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 61 / 69 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Flux de données Comment utiliser Doxygen ? Balises Diagrammes et graphes Personnalisation des sorties Enrichir la documentation 4 Pour aller plus loin ... F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 63 / 69 Quel outil de génération de documentation choisir ? Quel langage ? ... suite F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 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 - ENVOL 2012 Janvier 2013 65 / 69 Quel outil de génération de documentation choisir ? Quel OS ? F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 66 / 69 Quel outil de génération de documentation choisir ? Format de sortie F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 67 / 69 Références Quelques références Comparaison des outils de génération de documentation : en.wikipedia.org/wiki/Comparison_of_documentation_generators Doxygen : ◮ Doxygen (officiel) : ◮ Manuel d’utilisation Doxygen : ◮ Wikipedia : ◮ Initiation à Doxygen pour le C++ : www.doxygen.org <-> www.stack.nl/ dimitri/doxygen/ www.stack.nl/ dimitri/doxygen/manual.html fr.wikipedia.org/wiki/Doxygen franckh.developpez.com/tutoriels/outils/doxygen/ javadoc ◮ officiel : ◮ Wikipedia : http ://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html fr.wikipedia.org/wiki/Javadoc F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 68 / 69 Production (automatique) de documentations FIN Merci de votre attention Florent Langrognet F. Langrognet Production () (automatique) de documentations - ENVOL 2012 Janvier 2013 69 / 69
