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 \

Principales commandes : Permet aussi d’´ecriredu LATEXsimplifi´e • \file nom du fichier d´ecrit • \f{\f} pour les formules • \class math´ematiques • • \func \mainpage page principale • • \def nom de la macro \section • • \param param`etrespass´es \subsection • \brief br`evedescription • \details • \author • \date • \version • \copyright

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 (...)

.. toctree:: :maxdepth: 2 :caption: Contents:

modules

Indices and tables ======

* :ref:‘genindex‘ (...) 34/39 Introduction Doxygen Sphinx Remarques R´ef´erences

Documentation

make html

35/39 Introduction Doxygen Sphinx Remarques R´ef´erences

36/39 Introduction Doxygen Sphinx Remarques R´ef´erences

Usages

• Doxygen • est tr`eslargement utilis´e • est toujours d´evelopp´e • est assez lourd, mais s’automatise dans un Makefile ou CMake • donne un rendu par d´efauttr`esmoche • Sphinx • est surtout utilis´eavec Python • est concurrenc´epar d’autres g´en´erateursde documentation (changeants, eux aussi) • est assez simple (commentaires par d´efaut) • donne un rendu de type RestructuredText tr`esmoche

37/39 Introduction Doxygen Sphinx Remarques R´ef´erences

Une documentation ?

En pratique, pour utiliser - et contribuer `aun code, on a souvent besoin : • d’une documentation de l’interface de programmation (API) • un guide d’installation • des tests automatis´es • une explication (succinte) `al’usage des d´eveloppeurs donnant les principales caract´eristiquesde l’impl´ementation • des r´ef´erencesvers des articles, cas d’usages, etc. Parfois un bon README suffit (et des scripts tels que Makefile, CMake, etc.)

38/39 Introduction Doxygen Sphinx Remarques R´ef´erences

R´ef´erences

• https://fr.wikipedia.org/wiki/Doxygen • https://github.com/doxygen/doxygen • https://www.sphinx-doc.org/en/master/ • https://devblogs.microsoft.com/cppblog/clear-functional-c- documentation-with-sphinx-breathe-doxygen-cmake/

39/39