Doxygen/fr

Doxygen est un outil populaire pour générer de la documentation à partir de sources C ++ annotées. Il prend également en charge d'autres langages de programmation populaires tels que C#, PHP, Java et Python. Visitez le site Web Doxygen pour en savoir plus sur le système et consultez le Manuel Doxygen pour plus d'informations.

Ce document fournit une brève introduction à Doxygen, en particulier comment il est utilisé dans FreeCAD pour documenter ses sources. Consultez la page Documentation du code source pour obtenir des instructions sur la construction de la documentation FreeCAD, également hébergée en ligne sur le site Web FreeCAD API.



Doxygen avec du code C++
La section Mise en route (étape 3) du manuel Doxygen mentionne les méthodes de base pour documenter les sources.

Pour les membres, les classes et les espaces de noms, deux options sont disponibles:
 * 1) Placez un "bloc de documentation" spécial (un paragraphe commenté) avant la déclaration ou la définition de la fonction, du membre, de la classe ou de l'espace de noms. Pour les fichiers, classes et membres espaces de nom (variables), il est également autorisé de placer la documentation directement après le membre. Voir la section Blocs de commentaires spéciaux dans le manuel pour en savoir plus sur ces blocs.
 * 2) Placez un bloc de documentation spécial ailleurs (un autre fichier ou un autre emplacement dans le même fichier) et insérez une "commande structurelle" dans le bloc de documentation. Une commande structurelle lie un bloc de documentation à une certaine entité pouvant être documentée (une fonction, un membre, une variable, une classe, un espace de noms ou un fichier). Voir la section Documentation à d'autres endroits dans le manuel pour en savoir plus sur les commandes structurelles.

Remarque:
 * L'avantage de la première option est qu'il n'est pas nécessaire de répéter le nom de l'entité (fonction, membre, variable, classe ou espace de nom) car Doxygen analysera le code et extraira les informations pertinentes.
 * Les fichiers ne peuvent être documentés qu'en utilisant la deuxième option car il n'y a aucun moyen de mettre un bloc de documentation avant un fichier. Bien sûr, les membres de fichiers (fonctions, variables, typedefs, définit) n'ont pas besoin d'une commande structurelle explicite. il suffit de mettre un bloc de documentation avant ou après eux fonctionnera très bien.

Premier style: bloc de documentation avant le code
Généralement, vous souhaiterez documenter le code dans le fichier d'en-tête, juste avant la déclaration de classe ou le prototype de fonction. Ceci permet de garder la déclaration et la documentation proches les unes des autres, il est donc facile de mettre à jour la dernière si le premier change.

Le bloc spécial de documentation commence comme un commentaire de type C mais comporte un astérisque supplémentaire soit. Le bloc se termine par un correspondant. Une alternative consiste à utiliser des commentaires de style C ++ avec une barre oblique supplémentaire soit.

Deuxième style: bloc de documentation ailleurs
Sinon, la documentation peut être placée dans un autre fichier (ou dans le même fichier en haut ou en bas, ou ailleurs) à l'écart de la déclaration de classe ou du prototype de fonction. Dans ce cas, vous aurez des informations dupliquées, une fois dans le fichier source réel et une fois dans le fichier de documentation.

Premier fichier, :

Deuxième fichier, :

Dans ce cas, la commande structurelle est utilisée pour indiquer le fichier source documenté. Une commande structurelle indique que le code suivant est une fonction et que la commande  est utilisée pour décrire brièvement cette fonction.

Cette façon de documenter un fichier source est utile si vous souhaitez simplement ajouter de la documentation à votre projet sans ajouter de code réel. Lorsque vous placez un bloc de commentaires dans un fichier portant l’une des extensions suivantes, , ou alors Doxygen analysera les commentaires et construira la documentation appropriée mais masquera ce fichier auxiliaire de la liste des fichiers.

Le projet FreeCAD ajoute plusieurs fichiers se terminant par dans de nombreux répertoires afin de fournir une description ou des exemples du code correspondant. Il est important que ces fichiers soient correctement classés dans un groupe ou un espace de noms pour lequel Doxygen fournit des commandes auxiliaires telles que, et.

Exemple. Ce fichier dans l'arborescence des sources de FreeCAD donne une brève explication de l'espace de noms.

Un autre exemple est le fichier. Avant les détails d'implémentation des méthodes, il existe un bloc de documentation qui explique certains détails de la structure de commande de FreeCAD. Il comporte diverses commandes pour structurer la documentation. Il comprend même un exemple de code inclus dans une paire de mots-clés et. Lorsque le fichier est traité par Doxygen, cet exemple de code sera spécialement formaté pour se démarquer. Le mot clé est utilisé à plusieurs endroits pour créer des liens vers des sections, sous-sections, pages ou ancres nommées dans la documentation. De même, les commandes ou  affichent le libellé "See also" et fournissent un lien vers d'autres classes, fonctions, méthodes, variables, fichiers ou URL. Exemple

Exemple du projet VTK
Ceci est un exemple tiré de VTK, une bibliothèque de visualisation 3D utilisée pour présenter des données scientifiques, telles que des résultats d'éléments finis et des informations de nuage de points.

Une classe pour stocker une collection de coordonnées est définie dans un fichier d'en-tête C++. La partie supérieure du fichier est commentée et quelques mots-clés sont utilisés, tels que, et  pour indiquer les parties importantes. Dans la classe, avant les prototypes de méthode de classe, un bloc de texte commenté explique le rôle de la fonction et ses arguments.
 * Code source de vtkArrayCoordinates.h.
 * Doxygen a produit de la documentation pour la classe vtkArrayCoordinates.

Compiler la documentation


Pour générer la documentation du code source, il existe deux étapes de base:
 * 1) Créez un fichier de configuration pour contrôler la façon dont Doxygen traitera les fichiers source.
 * 2) Exécutez  sur cette configuration.

Le processus est décrit ci-dessous.


 * Assurez-vous que les programmes et  sont installés sur votre système. Il est également recommandé de disposer du programme  de Graphviz afin de générer des diagrammes avec les relations entre les classes et les espaces de noms. Sur les systèmes Linux, ces programmes peuvent être installés à partir de votre gestionnaire de paquets.

Assurez-vous d'être dans le même dossier que vos fichiers sources ou dans le répertoire toplevel de votre arborescence des sources si vous avez plusieurs fichiers sources dans différents sous-répertoires.


 * Exécutez pour créer un fichier de configuration nommé . Si vous omettez ce nom, la valeur par défaut sera  sans extension.
 * Il s’agit d’un gros fichier texte contenant de nombreuses variables avec leurs valeurs. Dans le manuel Doxygen, ces variables sont appelées "tags". Le fichier de configuration et toutes les balises sont décrits en détail dans la section Configuration du manuel. Vous pouvez ouvrir le fichier avec n’importe quel éditeur de texte et éditer la valeur de chaque balise selon vos besoins. Dans le même fichier, vous pouvez lire des commentaires expliquant chacune des balises et leurs valeurs par défaut.


 * Au lieu d'utiliser un éditeur de texte, vous pouvez lancer pour modifier plusieurs tags en même temps. Avec cette interface, vous pouvez définir de nombreuses propriétés telles que les informations de projet, le type de sortie (HTML et LaTeX), l’utilisation de Graphviz pour créer des diagrammes, les messages d’avertissement à afficher, les modèles de fichiers (extensions) à documenter ou à exclure, les filtres de saisie, les en-têtes facultatifs. et des bas de page pour les pages générées HTML, des options pour les sorties LaTeX, RTF, XML ou Docbook, et de nombreuses autres options.


 * Une autre option consiste à créer le fichier de configuration à partir de rien et à ajouter uniquement les balises souhaitées avec un éditeur de texte.
 * Une fois la configuration enregistrée, vous pouvez exécuter Doxygen sur ce fichier de configuration.


 * La documentation générée sera créée dans un dossier nommé . Il se composera de nombreuses pages HTML, d’images PNG pour les graphiques, de feuilles de style en cascade, de fichiers Javascript et éventuellement de nombreux sous-répertoires contenant plus de fichiers, selon la taille de votre code. Le point d’entrée dans la documentation est  que vous pouvez ouvrir avec un navigateur Web.

If you are writing new classes, functions or an entire new workbench, it is recommended that you run periodically to see that the documentation blocks, Markdown, and special commands are being read correctly, and that all public functions are fully documented. Please also read the documentation tips located in the source code.

When generating the complete FreeCAD documentation, you don't run directly. Instead, the project uses to configure the build environment, and then  triggers compilation of the FreeCAD sources and of the Doxygen documentation; this is explained in the source documentation page.

Doxygen markup
All Doxygen documentation commands start with a backslash or an at-symbol, at your preference. Normally the backslash is used, but occasionally the  is used to improve readability.

The commands can have one or more arguments. In the Doxygen manual the arguments are described as follows.
 * If braces are used the argument is a single word.
 * If braces are used the argument extends until the end of the line on which the command was found.
 * If  braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
 * If brackets are used the argument is optional.

Some of the most common keywords used in the FreeCAD documentation are presented here.
 * , see \defgroup, and Grouping.
 * , see \ingroup, and Grouping.
 * , see \addtogroup, and Grouping.
 * , see \author; indicates the author of this piece of code.
 * , see \brief; briefly describes the function.
 * , see \file; documents a source or header file.
 * , see \page; puts the information in a separate page, not directly related to one specific class, file or member.
 * , see \package; indicates documentation for a Java package (but also used with Python).
 * , see \fn; documents a function.
 * , see \var; documents a variable; it is equivalent to, , and.
 * , see \section; starts a section.
 * , see \subsection; starts a subsection.
 * , see \namespace; indicates information for a namespace.
 * , and, see \cond; defines a block to conditionally document or omit.
 * , see \a; displays the argument in italics for emphasis.
 * , see \param; indicates the parameter of a function.
 * , see \return; specifies the return value.
 * , see \sa; prints "See also".
 * , see \note; adds a paragraph to be used as a note.

Markdown support
Since Doxygen 1.8, Markdown syntax is recognized in documentation blocks. Markdown is a minimalistic formatting language inspired by plain text email which, similar to wiki syntax, intends to be simple and readable without requiring complicated code like that found in HTML, LaTeX or Doxygen's own commands. Markdown has gained popularity with free software, especially in online platforms like Github, as it allows creating documentation without using complicated code. See the Markdown support section in the Doxygen manual to learn more. Visit the Markdown website to learn more about the origin and philosophy of Markdown.

Doxygen supports a standard set of Markdown instructions, as well as some extensions such as Github Markdown. Some examples of Markdown formatting are presented next.

The following is standard Markdown. {{Code|code= Here is text for one paragraph.

We continue with more text in another paragraph.

This is a level 1 header

=
===========

This is a level 2 header


 * 1) This is a level 1 header


 * 1) This is level 3 header #######

> This is a block quote > spanning multiple lines

- Item 1

More text for this item.

- Item 2 * nested list item. * another nested item. - Item 3

1. First item. 2. Second item.


 * single asterisks: emphasis*

_single underscores_

**double asterisks: strong emphasis**

__double underscores__

This a normal paragraph

This is a code block

We continue with a normal paragraph again.

Use the `printf` function. Inline `code`.

[The link text](http://example.net/)

![Caption text](/path/to/img.jpg)

 }}

The following are Markdown extensions. [TOC]

First Header | Second Header - | - Content Cell | Content Cell Content Cell | Content Cell

~ {.py} class Dummy: pass ~
 * 1) A class

~ {.c} int func(int a, int b) { return a*b; } ~

``` int func(int a, int b) { return a*b; } ```

Parsing of documentation blocks
The text inside a special documentation block is parsed before it is written to the HTML and LaTeX output files. During parsing the following steps take place:
 * Markdown formatting is replaced by corresponding HTML or special commands.
 * The special commands inside the documentation are executed. See the section Special Commands in the manual for an explanation of each command.
 * If a line starts with some whitespace followed by one or more asterisks and then optionally more whitespace, then all whitespace and asterisks are removed.
 * All resulting blank lines are treated as paragraph separators.
 * Links are automatically created for words corresponding to documented classes or functions. If the word is preceded by a percentage symbol, then this symbol is removed, and no link is created for the word.
 * Links are created when certain patterns are found in the text. See the section Automatic link generation in the manual for more information.
 * HTML tags that are in the documentation are interpreted and converted to LaTeX equivalents for the LaTeX output. See the section HTML Commands in the manual for an explanation of each supported HTML tag.

Doxygen with Python code
Doxygen works best for statically typed languages like C++. However, it can also create documentation for Python files.

There are two ways to write documentation blocks for Python:
 * 1) The Pythonic way, using "docstrings", that is, a block of text surrounded by   immediately after the class or function definition.
 * 2) The Doxygen way, putting comments before the class or function definition; in this case double hash characters  are used to start the documentation block, and then a single hash character can be used in subsequent lines.

Note:
 * The first option is preferred to comply with PEP8, PEP257 and most style guidelines for writing Python (see 1, 2). It is recommended to use this style if you intend to produce documented sources using Sphinx, which is a very common tool to document Python code. If you use this style, Doxygen will be able to extract the comments verbatim, but Doxygen special commands starting with or  won't work.
 * The second option isn't the traditional Python style, but it allows you to use Doxygen's special commands like and.

First style: Pythonic documentation
In the following example one docstring is at the beginning to explain the general contents of this module (file). Then docstrings appear inside the function, class, and class method definitions. In this way, Doxygen will extract the comments and present them as is, without modification.

Second style: documentation block before the code
In the following example the documentation blocks start with double hash signs. One appears at the beginning to explain the general content of this module (file). Then there are blocks before the function, class, and class method definitions, and there is one block after a class variable. In this way, Doxygen will extract the documentation, recognize the special commands, , and , and format the text accordingly.

Compiling the documentation
Compilation of documentation proceeds the same as for C++ sources. If both Python files, and, with distinct commenting style are in the same directory, both will be processed.

The documentation should show similar information to the following, and create appropriate links to the individual modules and classes.

Converting the Pythonic style to Doxygen style
In the previous example, the Python file that is commented in a Doxygen style shows more detailed information and formatting for its classes, functions, and variables. The reason is that this style allows Doxygen to extract the special commands that start with or, while the Pythonic style does not. Therefore, it would be desirable to convert the Pythonic style to Doxygen style before compiling the documentation. This is possible with an auxiliary Python program called doxypypy. This program is inspired by an older program called doxypy, which would take the Pythonic  and convert them to the Doxygen comment blocks that start with a double hash. Doxypypy goes further than this, as it analyzes the docstrings and extracts items of interest like variables and arguments, and even doctests (example code in the docstrings).

Doxypypy can be installed using, the Python package installer.

If the command is used without the  option, it will require superuser (root) privileges to install the package, but this is not needed in most cases; use root permissions only if you are certain the package won't collide with your distribution provided packages.

If the package was installed as a user, it may reside in your home directory, for example, in. If this directory is not in your system's, the program will not be found. Therefore, add the directory to the variable, either in your  file, or in your  file.

Alternatively, you can create a symbolic link to the program, placing the link in a directory that is already included in the.

Once the program is installed, and accessible from the terminal, a Python file with Pythonic docstrings can be reformatted to Doxygen style with the following instructions. The program outputs the reformatted code to standard output, so redirect this output to a new file.

The original file has a comment at the top  that indicates the module or namespace that is being described by the file. This keyword is not interpreted when using triple quotes in the comment block.

In the new file the commenting style is changed so the line becomes, which now will be interpreted by Doxygen. However, to be interpreted correctly, the argument has to be edited manually to match the new module (file) name; after doing this the line should be.

(the top is manually edited, the rest stays the same)

To compile, create the configuration, and run in the toplevel directory that contains the files.

The documentation should show similar information to the following, and create appropriate links to the individual modules.

Converting the comment style on the fly
In the previous example, the conversion of the documentation blocks was done manually with only one source file. Ideally we want this conversion to occur automatically, on the fly, with any number of Python files. To do this, the Doxygen configuration must be edited accordingly.

To start, don't use the program directly; instead, create the configuration file with, then edit the created , and modify the following tag.

What this does is that files that match the pattern, all files with a extension ending in, will go through the program. Every time Doxygen encounters such file in the source tree, the file name will be passed as the first argument to this program.

The program does not exist by default; it should be created as a shell script to run  with the appropriate options, and to take a file as its first argument.

After saving this shell script, make sure it has execute permissions, and that it is located in a directory contained in your system's.

On Windows systems, a batch file can be used in a similar way.

With this configuration done, the command can be run to generate the documentation as usual. Every Python file using Pythonic  will be reformatted on the fly to use  style comments, and then will be processed by Doxygen, which now will be able to interpret the special commands and Mardown syntax. The original source code won't be modified, and no temporary file with a different name needs to be created as in the previous section; therefore, if a instruction is found, it doesn't need to be changed manually.

Note that existing Python files which already use the style for their comment blocks won't be affected by the  filter, and will be processed by Doxygen normally.



Python code quality check
To use the automatic conversion of documentation blocks it is important that the original Python sources are correctly written, following the Pythonic guidelines in PEP8 and PEP257. Sloppily written code will cause to fail when processing the file, and thus Doxygen will be unable to format the documentation correctly.

The following commenting styles will not allow parsing of the docstrings by, so they should be avoided.

Always use triple quotes for the docstrings, and make sure they immediately follow the class or function declaration.

It is also a good idea to verify the quality of your Python code with a tool such as flake8 (Gitlab). Flake8 primarily combines three tools, Pyflakes, Pycodestyle (formerly pep8), and the McCabe complexity checker, in order to enforce proper Pythonic style.

To check all files inside a source tree use.

If the project demands it, some code checks deemed too strict can be ignored. The error codes can be consulted in the Pycodestyle documentation.

In similar way, a program that primarily checks that comments comply with PEP257 is Pydocstyle. The error codes can be consulted in the Pydocstyle documentation.

Also use it with to perform docstring checks on all source files.

Source documentation with Sphinx
Sphinx is the most popular system to document Python source code. However, since FreeCAD's core functions and workbenches are written in C++ it was deemed that Doxygen is a better documentation tool for this project.

While Sphinx can natively parse Python docstrings, it requires a bit more work to parse C++ sources. The Breathe (Github) project is an attempt at bridging the gap between Sphinx and Doxygen, in order to integrate both Python and C++ source code documentation in the same system. First, Doxygen needs to be configured to output an XML file; the XML output is then read by Breathe, and converted to suitable input for Sphinx.

See the Quick start guide in the Breathe documentation to know more about this process.

See this answer in Stackoverflow for other alternatives to documenting C++ and Python code together in the same project.