Discussion :

[Neckara]

Bonjour,

Il n'y a pas vraiment de forums approprié pour parler de Doxygen, donc je vais tenter ma chance ici.

Pour générer une documentation avec doxygen, il est possible de générer des TAGFILE dans des sous-dossiers puis de générer une documentation globale incluant tous ces TAGFILE.

Ce qui permet de compiler la documentation de chaque sous-dossier séparément, ce qui est assez pratique pour des histoires de mises à jour.

Mais voilà, je voudrais faire une documentation globale de plusieurs sous-dossier qui sont en fait plutôt des "sous-projets". En effet, j'ai des bibliothèques, des programmes qui auront alors leur propre @mainpage et leur propres "Related files".

Si je génère une documentation globale, à part quelques exceptions, tout sera bon au niveau des classes/méthodes/macro. Mais en revanche, les "Related files" sont fusionnés et je ne sais pas non-plus comment gérer les différents @mainpage.

Est-ce que vous auriez, en somme, une astuce pour réussir à obtenir une jolie documentation regroupant plusieurs "projets" ?

[koala01]

Salut,

Personnellement, je travaillerais plutôt différemment, en utilisant les commandes @defgroup et autres.

Cette commande permet de séparer ton projet principal en différents modules (un par group que tu définis). Tu peux ensuite spécifier le module dans lequel tu souhaites travailler grâce à la commande @ingroup.

Ainsi, tu peux par exemple créer un premier fichier (mettons groups.dox) qui définis les différents "sous projets" de ton projet principal, sous une forme proche de

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/** @defgroup groupe1 Description succinte du projet
  *
  * Description détaillée du projet
  *
  */
/** @defgroup groupe2 Description succinte du projet
  *
  * Description détaillée du projet
  *
  */
/* ... */
/** @defgroup  groupeN Description succinte du projet
  *
  * Description détaillée du projet
  *
  */

Cela aura pour résultat de provoquer la création d'un onglet supplémentaire (Modules) au niveau de la documentation générée qui reprendra la liste des différents modules ainsi créé.

A partir de là, tu peux sans aucun problème rajouter "n'importe quoi" dans le module créé grâce à la commande @ingroup :

Tu peux fournir une page qui servira de page principale sous une forme qui ressemblerait à

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
/** @page idDeLaPage le titre de la page
  *
  * @ingroup groupe1 
  * tout le texte que tu veux voir apparaitre sur la page "principale" du module
  *
  */

tout comme tu peux préciser le groupe dans le cadre duquel tes fonctions / classes / types sont définis, sous une forme proche de

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
/** La fonction qui fait prout
   *
   * tout ce que tu veux dire à son sujet
   * @ingroup groupe1
   *
   */
void proutFunction();
/** La classe méga géniale du groupe N
   *
   * Tout ce que tu veux en dire
   * @ingroup groupN
   *
   */
class MaClasse{
    /* ... */
};

Au final, pour chaque module, tu disposera d'une page qui sera composée :

1. De tous les types et fonctions définis dans le groupe
2. de la description détaillée du projet (si tu en as fourni lorsque tu as utilisé la commande @defgroup)
3. De l'ensemble des pages pour lesquelles tu as indiqué un groupe spécifique avec la commande @ingroup

NOTE : Il est tout à fait possible d'obtenir une seule grande page contenant le texte de différentes pages si tu utilises la commande @ingroup pour plus d'une page. Je ne suis pas sur de la manière dont ces différentes pages sont ajoutées mais je ne serais pas étonné que le tri soit effectué sur base des identifiants de pages que tu définis au travers de la commande @page

[Neckara]

Merci, je vais tester ça dès que je le pourrais

[Neckara]

Merci ça marche très bien

Juste encore un petit problème avec mes fichier .md dans les "related page", je ne sais pas trop comment les ajouter au module au lieu qu'ils se retrouvent tous fusionnés.

Par contre, ce que je trouve dommage, c'est que lorsqu'on regarde la documentation d'une classe, on ne voit pas dans quel module il appartient (par contre, il est bien dans la page du module).

Sinon, il faudra aussi que je trouve si on peut documenter des pages de sources (description, auteur, etc...). J'arrive à les avoir dans la doc mais je n'ai pas encore trouvé comment les documenter.

[Neckara]

Alors, en ajoutant @page md_page2 Md Page 2, dans les fichier .md, j'arrive à éviter la fusion.

Malheureusement, si je rajoute @ingroup, il va être intégré à la page de présentation du module au lieu de proposer un lien

Je continue à chercher.

EDIT : Second problème résolu en ajoutant :
module /ref nom_du_module.

EDIT : Problème des documentation des pages sources, résolu avec @file.

[Neckara]

Bon,

Doxygen n'a pas l'air de supporter encore très bien les markdown

Par exemple, il ne fait pas de retours à la ligne quand on a deux espaces.
Ce qui va me poser problème vu que les fichiers markdown sont aussi utilisé sur github...

Après, pour les related files, je ne vois pas du tout comment faire.
Soit j'ai tous les fichiers dans "related files" soit j'ai le contenu des fichiers dans la page de présentation du module

[koala01]

Merci ça marche très bien

Juste encore un petit problème avec mes fichier .md dans les "related page", je ne sais pas trop comment les ajouter au module au lieu qu'ils se retrouvent tous fusionnés.

Pour ces fichiers, je ne peux pas t'aider, désolé

Par contre, ce que je trouve dommage, c'est que lorsqu'on regarde la documentation d'une classe, on ne voit pas dans quel module il appartient (par contre, il est bien dans la page du module).

Là, par contre, je peux t'assurer que si tu utilises la commande @ingroup dans le cartouche de ta classe, tu obtiendra un résultat qui ressemblera à

Référence de la classe le nom de ta classe
< description du module dont elle fait partie>

et que <description du module dont elle fait partie> est un lien qui pointe vers la page principale du module en question

Sinon, il faudra aussi que je trouve si on peut documenter des pages de sources (description, auteur, etc...). J'arrive à les avoir dans la doc mais je n'ai pas encore trouvé comment les documenter.

Pour les fichiers sources, cela prend la forme de

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
/** @file nom du fichier
  * @brief breve descritpion du contenu du fichier
  *
  * <tu peux mettre des informations en plus ici>
  * @author nom prenom <e-mail?>
  * @version <numéro de version du fichier> (incrémenté en cas de changements)
  * @date <date de création / modification>
  *  <tu peux utiliser @todo, @bug, et autres ici aussi>
  *
  * @ingroup <nom du groupe>
  *
  */

que tu placera, idéalement, tout en haut du fichier en question (ou que tu peux placer dans un fichier à part, mais bon... pas cool pour les évolutions ), juste avant (ou juste après) les informations de licence, si tu veux les mettre dans tes fichiers

La commande @ingroup (ni aucune autre d'ailleurs, à l'exception de @file )n'est, bien sur, pas obligatoire. Mais elle permet de rajouter en plus la liste des fichiers qui font partie du module sur la page principale de celui-ci

[Neckara]

Merci pour tes réponses.

Là, par contre, je peux t'assurer que si tu utilises la commande @ingroup dans le cartouche de ta classe, tu obtiendra un résultat qui ressemblera à
et que <description du module dont elle fait partie> est un lien qui pointe vers la page principale du module en question

Je n'avais pas vu, c'est vraiment "caché" ça

Pour le reste :
- j'ai ajouté des balises html quand doxygen ne supporte pas vraiment certains aspects des markdown ;
- j'ai ajouté :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
<sub>
	@page LPHeader_INSTALL LPHeader/INSTALL
</sub>

Pour "trier" les fichiers dans "Related pages".

Par contre :
- impossible de cacher "@page LPHeader_INSTALL LPHeader/INSTALL" sur github ;
- doxygen est très sale au niveau des noms de pages donc quand j'ai un lien vers une autre page, je ne peux pas faire grand chose et je suis obligé de laisser un lien invalide