Introduction Doxygen Sphinx Remarques R´ef´erences G´en´erationautomatique de la documentation d'un code Anne Cadiou Laboratoire de M´ecaniquedes Fluides et d'Acoustique Ateliers et S´eminairesPour l'Informatique et le Calcul Scientifique PMCS2I - LMFA Vendredi 4 juin 2021 1/39 Introduction Doxygen Sphinx Remarques R´ef´erences Motivation Pourquoi g´en´ererautomatiquement une documentation ? • destin´e`amieux comprendre de un code, en faciliter la lecture et le d´eveloppement • les lignes de codes parlent par elles-m^emedu comment, mais il est parfois n´ecessaired'ajouter un commentaire sur le pourquoi • des commentaires sont pr´esentsdans le code, pour expliquer ou justifier les lignes de codes • ´ecrireun document `apart du code est difficile `amaintenir `ajour • avoir un syst`emequi extrait les commentaires du code permet aussi d'am´eliorer la qualit´ede ces commenaires • extraire une documentation du code permet aussi de tenir compte de la structure du code Un syst`emede g´en´erationautomatique de documentation `apartir d'un code extrait des informations `apartir des sources et les compile en une documentation qui ´evolue automatiquement avec le code. 2/39 Introduction Doxygen Sphinx Remarques R´ef´erences Outils existants tr`esnombreux https://en.wikipedia.org/wiki/Comparison of documentation generators cela d´epend • de leur licence • du langage avec lequel le code `adocumenter est ´ecrit • de leurs int´egrationdans d'´eventuelsIDE • de leurs formats de sortie • de la taille du code `adocumenter • des syst`emesd'exploitation support´es,etc. Outils les plus r´epandus en C, C++, FORTRAN, Python : • Doxygen • Sphinx Certains sont d´edi´es`aun langage, par exemple pydoctor (rempla¸cant d'Epydoc), pdoc ou pydoc pour Python, ROBODoc, FORD pour FORTRAN, etc. 3/39 Introduction Doxygen Sphinx Remarques R´ef´erences Doxygen (1997-) derni`ereversion 2021 Langages support´es C++, C, Python, FORTRAN, Objective-C, C#, PHP, Java, IDL, VHDL, D Bas´esur un ensemble de balises `aajouter aux sources Formats de sortie • documentation `apartir des sources document´ees: HTML, LATEX, RTF (MS-Word), PS, PDF, XML, Unix man pages • extraction de la structure du code pour des sources document´eesou non. g´en`ereles graphes de d´ependances, les h´eritagesde classes, etc. • fonctionne sous Mac OS X, Linux, Windows • Eclipse, VS Code, vim (:Dox), • sous licence GPL 4/39 Introduction Doxygen Sphinx Remarques R´ef´erences Installation sous ubuntu sudo apt-get install doxygen doxygen-gui doxygen-doc Pour ceux qui aiment les interfaces graphiques : sudo apt-get install graphviz qui se lance avec la commande doxywizard & Doxygen se lance en ligne de commande par doxygen 5/39 Introduction Doxygen Sphinx Remarques R´ef´erences Balises C ou C++ FORTRAN Python /*! !< """ * \brief !! \brief \brief * \value !! \value \value */ !! """ ou ou /** !< Pas vraiment optimal * \brief !< \brief pour Python * \value !< \value */ !< (d'autres styles existent) Commentaires priv´es // sur une ligne ! ligne exclue de la doc automatique /* * sur * plusieurs lignes */ 6/39 Introduction Doxygen Sphinx Remarques R´ef´erences Commandes Pr´efix´eespar @ ou n Principales commandes : Permet aussi d'´ecriredu LATEXsimplifi´e • nfile nom du fichier d´ecrit • nff nfg pour les formules • nclass math´ematiques • • nfunc nmainpage page principale • • ndef nom de la macro nsection • • nparam param`etrespass´es nsubsection • nbrief br`evedescription • ndetails • nauthor • ndate • nversion • ncopyright 7/39 Introduction Doxygen Sphinx Remarques R´ef´erences Emplacement Par d´efaut,les commentaires r´ecup´er´espar Doxygen doivent ^etreplac´esavant la structure `adocumenter. Exemple : /** * \brief The function bar. * * \details This function does something. * * \param[in] a Description of parameter a. * \param[out] b Description of the parameter b. * \param[in,out] c Description of the parameter c. * * \return The error return code of the function. * */ errcode_t bar(int a, int b, int c) { /** More detailed description inside the code */ } 8/39 Introduction Doxygen Sphinx Remarques R´ef´erences Utilisation Premi`ere´etape : g´en´ererle fichier de configuration (Doxyfile par d´efaut) doxygen -g Deuxi`eme´etape : variables `arenseigner PROJECT_NAME = Nom du code INPUT = Localisation des sources du code USE_MATHJAX = YES # permet d'inserer des formules de math en \LaTeX GENERATE_XML = YES # permet l'interface avec Sphinx utile pour le FORTRAN EXTRACT_ALL = YES OPTIMIZE_FOR_FORTRAN = YES utile pour les graphes d'appel CALL_GRAPH = YES CALLER_GRAPH = YES Derni`ere´etape : g´en´ererla documentation doxygen Doxyfile 9/39 Introduction Doxygen Sphinx Remarques R´ef´erences Exemple en FORTRAN Codes source project/ src/ burgers.f90 Makefile mexact.f90 mio.f90 mscheme.f90 msolver.f90 bin/ 10/39 Introduction Doxygen Sphinx Remarques R´ef´erences Ajout de balises de commentaires program burgers !> @mainpage Solve Burger's equations !! @author Anne Cadiou !! @date 19/04/2021 !! !! @details !! solve the Burgers'1D equation !! @f\[ !!\frac{\partialu}{\partialt}+u\frac{\partialu}{\partialx}=\nu\frac{\ partial^2u}{\partialx^2} !! @f\] !! !! with either one of these schemes !!- time explicit Euler and second order space centered !!- semi-implicit Crank-Nicolson !! use mexact use msolver use mscheme use mio implicit none integer, parameter:: dp = kind(0.D0) (...) 11/39 Introduction Doxygen Sphinx Remarques R´ef´erences G´en´erationdu fichier de configuration Cr´eationd'un r´epertoire o`ug´en´ererla documentation mkdir -p docs En ligne de commande doxygen -g Avec l'interface graphique doxywizard & 12/39 Introduction Doxygen Sphinx Remarques R´ef´erences 13/39 Introduction Doxygen Sphinx Remarques R´ef´erences 14/39 Introduction Doxygen Sphinx Remarques R´ef´erences 15/39 Introduction Doxygen Sphinx Remarques R´ef´erences 16/39 Introduction Doxygen Sphinx Remarques R´ef´erences 17/39 Introduction Doxygen Sphinx Remarques R´ef´erences 18/39 Introduction Doxygen Sphinx Remarques R´ef´erences 19/39 Introduction Doxygen Sphinx Remarques R´ef´erences 20/39 Introduction Doxygen Sphinx Remarques R´ef´erences 21/39 Introduction Doxygen Sphinx Remarques R´ef´erences 22/39 Introduction Doxygen Sphinx Remarques R´ef´erences 23/39 Introduction Doxygen Sphinx Remarques R´ef´erences Documentation project/ docs/ html/ latex/ xml/ src/ Lecture des pages firefox html/index.html G´en´erationd'un pdf LATEX cd latex make 24/39 Introduction Doxygen Sphinx Remarques R´ef´erences 25/39 Introduction Doxygen Sphinx Remarques R´ef´erences 26/39 Introduction Doxygen Sphinx Remarques R´ef´erences 27/39 Introduction Doxygen Sphinx Remarques R´ef´erences 28/39 Introduction Doxygen Sphinx Remarques R´ef´erences Sphinx (2008-) derni`ere version 2018 Langages support´es Python, PHP, JavaScript Expoite les commentaires pr´esentsdans les sources Formats de sortie • documentation `apartir des sources document´ees: HTML, LATEX, PS, PDF, XML, Unix man pages • extensions • fonctionne sous Mac OS X, Linux, Windows • sous licence BSD 29/39 Introduction Doxygen Sphinx Remarques R´ef´erences Exemple project/ src/ data manager.py physical system.py run.py solver.py 30/39 Introduction Doxygen Sphinx Remarques R´ef´erences Utilisation Premi`ere´etape : initialiser la documentation sphinx-quickstart R´epondre aux questions. Recommandation : s´eparer les r´epertoires build et source Welcome to the Sphinx 1.8.5 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: . You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y (...) 31/39 Introduction Doxygen Sphinx Remarques R´ef´erences (...) > Create Makefile? (y/n) [y]: y > Create Windows command file? (y/n) [y]: n Creating file ./source/conf.py. Creating file ./source/index.rst. Creating file ./Makefile. Finished: An initial directory structure has been created. You should now populate your master file ./source/index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. La documentation sera g´en´er´eedans source (ici renomm´een docs) mv source docs dans ce cas, modifier aussi dans le Makefile SOURCEDIR = docs soit dans textttmake.bat pour Windows set SOURCEDIR=docs 32/39 Introduction Doxygen Sphinx Remarques R´ef´erences Configuration cd docs Dans le fichier conf.py expliciter le chemin vers les modules import os import sys sys.path.insert(0, os.path.abspath('../src')) et ajouter l'extension vers l'auto-documentation extensions = [ 'sphinx.ext.autodoc' ] Le style peut ^etremodifi´e,par exemple au lieu de alabaster, pour passer `a rtd, ajouter extensions = [ 'sphinx.ext.autodoc', 'sphinx_rtd_theme', ] html_theme = 'sphinx_rtd_theme' 33/39 Introduction Doxygen Sphinx Remarques R´ef´erences G´en´erationautomatique A` la racine du projet (o`use trouve le Makefile) ex´ecuter sphinx-apidoc -f -o docs src cela g´en`ereles pages de documentation pour chaque fichier python et un document modules Creating file docs/data_manager.rst. Creating file docs/physical_system.rst. Creating file docs/run.rst. Creating file docs/solver.rst. Creating file docs/modules.rst. Ajouter le document modules dans le document principal docs/index.rst g´en´er´epar sphinx .. Lorenz documentation master file, created by sphinx-quickstart