Doxygen : documentation de sous-projets

Version imprimable

17/11/2013, 21h44
Neckara

Doxygen : documentation de sous-projets

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" ?

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:

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:

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:

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 :

De tous les types et fonctions définis dans le groupe
de la description détaillée du projet (si tu en as fourni lorsque tu as utilisé la commande @defgroup)
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 ;)

18/11/2013, 06h44
Neckara

Merci, je vais tester ça dès que je le pourrais :ccool:
18/11/2013, 10h13
Neckara

Merci ça marche très bien :ccool:

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.
18/11/2013, 13h41
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 :aie:

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.
18/11/2013, 14h50
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 :cry:

Citation:

Envoyé par Neckara

Merci ça marche très bien :ccool:

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é

Citation:

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 à

Citation:

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 :D

Citation:

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:

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 :D

18/11/2013, 19h18
Neckara
Merci pour tes réponses.

Citation:

Envoyé par koala01

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 :D

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

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

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 :aie: 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 :?

Ben tu peux utiliser @ref <identifiant de page / de la section> sans aucun problème.

Cela te créera un lien qui prend la forme de <titre de la page / de la section>.

Tu peux, bien sur, utiliser cette commande strictement n'importe où ;)

Tu n'as, a priori, absolument pas à t'inquiéter du nom définitif de la page, doxygen s'occupe de gérer tout cela ;)

Tout ce qu'il faut, c'est que tu dispose d'un identifiant unique ;)

Tu pourrais très bien avoir des références croisées sous une forme proche de
Code:

1 2 3 4 5 /** @page page1 Le titre principal * * blahblah... * @ref section3 */
et pour un autre fichier
Code:

1 2 3 4 5 6 7 8 9 10 /** @page page3 le titre de la page * * comme je l'ai fait savoir dans @page1 , blablah * * @section section3 titre de la section * * Notez que la classe MaClasse a pour objectif de * blahblah... * */
Dans page1, tu auras le lien vers la section 3 de la page3, et, dans page3, tu auras les liens vers MaClasse et vers la page1 ;)

Note au passage que, si tu as installé doxygen dans le dossier par défaut, tu trouvera toute la documentation sur les commandes que je t'indique le fichier file:///C:/Program%20Files/doxygen/html/commands.html ;)

18/11/2013, 19h41
Neckara

En fait le problème, c'est que le fichier markdown est lu aussi bien par github que par doxygen :aie:

Donc pour des ancres, je n'ai aucun problème, mais pour mettre un lien de fichier dans le fichier markdown... :aie:
18/11/2013, 19h45
koala01
Ah, au fait,

Citation:

Envoyé par Neckara

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

Tu peux normalement définir une css personnalisée que doxygen devrait utiliser.

Tu devrais pouvoir rendre cet aspect plus visible en définissant des valeurs peut être plus adéquates pourdiv.ingroups.

Par défaut, elles sont à
Code:

1 2 3 4 5 6 div.ingroups { font-size: 8pt; width: 50%; text-align: left; }
mais tu pourrait, par exemple, essayer quelque chose comme
Code:

1 2 3 4 5 pourdiv.ingroups{ font-size: 15pt; width: 50%; text-align: left; }
;)
[EDIT]A utiliser comme HTML_EXTRA_STYLESHEET si tu ne veux pas devoir redéfinir toutes les parties de la css de base :aie:
18/11/2013, 19h47
koala01

Citation:

Envoyé par Neckara

En fait le problème, c'est que le fichier markdown est lu aussi bien par github que par doxygen :aie:

Donc pour des ancres, je n'ai aucun problème, mais pour mettre un lien de fichier dans le fichier markdown... :aie:

Excuses moi, mais comme je n'ai absolument aucune idée de ce que sont les fichier makdown dont tu me parle :aie:

Pourrais tu m'en montrer un exemple, histoire que je sache à quoi je suis confronté :question:

En gros, c'est un fichier qui est ensuite "traduit" en HTML :

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
<sub>
	@page LPHeader_INSTALL LPHeader/INSTALL
</sub>
 
# INSTALL
 
Specific installation is 
See also the main <a href="../../INSTALL.md">INSTALL</a>
 
## Summary
 
<a href="#i-requirement">I  Requirement</a><br/>
<a href="#ii-build">II Build</a><br/>
<a href="#iii-install">III Install</a><br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#1-linux">1) Linux</a><br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#2-mac">2) MAC</a><br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#3-windows">3) Windows</a>
 
### <a name="i-requirement">I Requirement</a>
 
To build this you must have :
 
* g++ >= 4.8
* make
* cmake >= 2.8
* boost >= 1.53
* LPException
 
You can download some requirement on your website (<a href="http://wwww.last-dungeon.fr">last-dungeon.fr</a>).
 
### II Build
 
To build the project, we use CMake which can generate project file like :
 
* Makefile ;
* Code::block project files ;
* QtCreator porject files ;
* and others...
 
Some IDE can load a project from MakeFile or/and CMakeLists.txt like QtCreator.
 
How to build :
 
* Launch CMake in the root directories. CMake will take care of all.
* If a requirement is missing, download and install it then restart CMake.
 
Make sure you have all requirements.
 
You will find all binaries into the bin directory and the header into the includes
directory (cf <a href="../../README.md">README</a>).
 
### III Install
 
CMake create a Makefile when you build something. Do a "make install" on it can
install it.
 
#### 1 Linux
 
Copy all .so file required into the folder /usr/lib.
 
Create a symbolic link in the folder /usr/bin to the executable :
ln -s /usr/bin/executable path/executable
 
#### 2 Mac
 
#### 3 Windows
 
Add the .dll into the executable's folder.

Résultat : https://github.com/LastDungeon/LastP...der/INSTALL.md

(juste le "toto" qui est en trop).

18/11/2013, 20h07
koala01

Ah oui, ok...

Il faut savoir que, par défaut, doxygen va parser une quantité non négligable d'extensions, dont les extensions *md et markdown...

La bonne question est de savoir si, pour une raison ou une autre, il est intéressant de le laisser faire :aie:

Je ne suis personnellement pas forcément persuadé qu'il soit opportun de le laisser faire car, en définitive, les fichiers markdown me semblent plus proches des fichiers d'informations utilisés sur github qu'autre chose.

Et comme les informations que tu trouves dans ces fichiers n'a, en définitive, pas "grand chose" à voir avec le but d'une documentation doxygen, je te proposerais bien de supprimer cette extension de la liste des extensions parsées et de placer simplement un lien extérieur qui pointe directement vers github.

Cela permettra sans doute d'éviter d'avoir des informations dupliquées suite au parsing d'informations destinées à différents systèmes ;)
18/11/2013, 20h12
Neckara

Ben j'ai plutôt envie de partir du principe que ces fichiers ont quand même une petite utilité, je n'ai pas de fichier README (ou INSTALL) mais un README.md par exemple.

Et vu qu'en ouvrant avec un éditeur "ordinaire", c'est pas si lisible que ça, je pensais que ce serait bien de pouvoir les voir via la doc.

Là, il ne devrait y avoir que quelques liens qui ne marcheront pas, mais pour le reste, je pense que ça devrait être "pas trop mal".
18/11/2013, 22h47
koala01

Ceci dit, je pense que tu devrais un tout petit peu réfléchir à l'utilisation qui est faite des différents fichiers.

Typiquement, les readme et autres INSTALL ont pour but de donner un aperçu rapide du projet et méritent sans doute amplement d'être au pur format texte (comprends: sans balisage d'aucune sorte, qu'il soit markdown-style ou doxygen-style)

Si tu t'intéresse un tout petit peu aux autotools (le système qui permet de générer les Makefile sous linux), tu remarquera qu'automake vérifie la présence de fichiers comme README, AUTHORS, ChangeLog ou LICENSE.

Ca, ce sont typiquement des fichiers de texte brut, et ils ont l'énorme avantage d'être parfaitement affichables dans un navigateur.

Si on y réfléchit un tout petit peu, les fichier *.md font, malgré tout, "double emplois" par rapport à ces fichiers.

Pour certains, ce n'est pas *trop* grave car ils évoluent peu (je pense au fichier README ou au fichier LICENSE).

Tu peux donc parfaitement envisager d'avoir un README, un README.md et un README.dox qui permettront d'afficher le même contenu dans un éditeur de texte "classique", au travers de l'interface de github ou d'avoir une page relative dans doxygen ;)

Par contre, pour ce qui est de ChangeLog:

Déjà, tu devrais séparer les changements et les todo: le ChangeLog a pour but d'indiquer ce qui a changé et quand alors que la todo-list permet de savoir "ce qui reste à faire".

Typiquement, il n'est pas rare que l'ajout d'une ligne au changelog occasionne le retrait d'une ligne équivalente dans la todo-list (enfin, c'est ce qu'on espère à chaque fois) :D

Et comme c'est un fichier qui est susceptible de changer régulièrement, le plus simple me semble de le garder au format texte brut: une liste de date et de changement effectués ;)

Après tout, tu dois appréhender ce fichier dans une logique d'intégration continue : tu es secondé par github pour le versionning et d'un bug tracker pour les issues qu'il faut résoudre, ou qui sont résolues ainsi que pour les demandes auxquelles il s'agit de réfléchir.

Tu peux sans problème faire référence à une issue particulière dans le texte des changements apportés, mais il ne me semble vraiment pas utile d'essayer de garder une liste ordonnée, triée par année, mois et jour : Si tu pars dans cette direction, tu ne t'en sortira jamais par la suite.

C'est d'autant plus vrai que certains outils sont parfaitement en mesure de parser correctement une ligne de modification qui ressemblerait à

Code:

YYYY/MM/DD fixed issues #15 #17 and #495

ou à

Code:

YYYY/MM/DD added some useful functionnality

Bref, on en revient toujours au même point : la solution la plus simple est toujours la meilleure :D

Et, pour finir, il y a les listes de choses à faires, des bugs et des fonctionnalités dépréciées.

Les deux premières seront sans doute fortement mises en parallèle avec ton bugtracker, mais il n'empêche que, si tu veux expliciter les choses, cela devrait être fait au niveau de fichiers séparés (TODO et BUGS (ou KnownBugs) ).

Ce sont, encore une fois, des fichiers qui évolueront rapidement et qui, de toutes manières, nécessiteront une intervention dans le code source.

Or, dés que l'on parle de code source, on peut parler de doxygen, des flags d'extraction GENERATE_TODOLIST, GENERATE_TESTLIST, GENERATE_BUGLIST et GENERATE_DEPRECATEDLIST ainsi que des commandes respectives @todo, @test, @bug et @deprecated.

Toutes ces commandes ont pour résultat de rajouter une page relative correspondante dans la documentation doxygen ;)

La question qu'il devient alors intéressant de se poser, c'est -- étant donné que doxygen fournit la documentation à l'utilisateur (en gardant en tête que le développeur est le premier utilisateur de ce qu'il développe :D ) -- Qu'est ce qui peut rester dans la documentation et qu'est-ce qui est intéressant d'exposer "par ailleurs":question:

Et cette question en amène directement une autre : Faut il un niveau de détail similaire pour ce qui fait partie de la documentation destinée à l'utilisateur (ou au développeur) et pour ce qui est "dupliqué" par ailleurs :question:

Quelque part, doxygen nous donne déjà une partie de la réponse en permettant de définir explicitement deux groupes distincts d'utilisateurs : les développeurs d'une part, qui ont une connaissance plus "profonde" du projet et les utilisateurs "simples" de l'autre, qui se contentent... d'utiliser le projet.

Tu pourrais donc parfaitement envisager d'avoir d'un coté un simple fichier de texte brut TODO qui reprend une liste "générique" des choses à faire, sans entrer réellement dans les détais (ou des bugs à résoudre, ou des modifications apportées, ...) et, de l'autre, utiliser les commandes dont j'ai parlé plus haut pour faire en sorte que doxygen génère automatiquement les listes plus fines ;)

Enfin, tout cela pour dire que, de toutes manières, tu n'arriveras sans doute jamais à éviter une certaine dose de répétition dans les différents fichiers.

Le tout est d'essayer de l'éviter au mieux, et, surtout, de voir quelle information est absolument indispensable à quel type d'utilisateur, ainsi que le niveau de détails à donner ;)
19/11/2013, 06h29
Neckara

Citation:

Envoyé par koala01

Typiquement, les readme et autres INSTALL ont pour but de donner un aperçu rapide du projet et méritent sans doute amplement d'être au pur format texte (comprends: sans balisage d'aucune sorte, qu'il soit markdown-style ou doxygen-style)

Les fichiers README.md sont par exemple directement affichés lorsqu'on affiche le dossier dans github.
Je trouve que c'est quand même assez pratique et cela permet aussi de soigner la mise en page.

Citation:

Si tu t'intéresse un tout petit peu aux autotools (le système qui permet de générer les Makefile sous linux), tu remarquera qu'automake vérifie la présence de fichiers comme README, AUTHORS, ChangeLog ou LICENSE.

J'utilise CMake (il est super utile \o/).

Citation:

Ca, ce sont typiquement des fichiers de texte brut, et ils ont l'énorme avantage d'être parfaitement affichables dans un navigateur.

Au pire, je peux simplement faire un "mini-README" disant de générer la doc ou de regarder sur le dépôt github?

Citation:

Déjà, tu devrais séparer les changements et les todo: le ChangeLog a pour but d'indiquer ce qui a changé et quand alors que la todo-list permet de savoir "ce qui reste à faire".

Disons que je trouve pratique de regrouper ces deux informations.
C'est un peu comme si je disais "ce qui va changer".

Citation:

Tu peux sans problème faire référence à une issue particulière dans le texte des changements apportés, mais il ne me semble vraiment pas utile d'essayer de garder une liste ordonnée, triée par année, mois et jour : Si tu pars dans cette direction, tu ne t'en sortira jamais par la suite.

Je ne vais pas non-plus rajouter une ligne par issue résolue.
Mais je trouve pratique et encourageant de résumer ce qui a été fait quitte à résumer par la suite ce qui a été fait dans le mois par exemple.
Par exemple, j'ai du faire une bonne 30ène de commit en deux jours.
Il est beaucoup plus simple pour moi de lire quelques lignes de changelogs que de relire mes commits.

Citation:

Tu pourrais donc parfaitement envisager d'avoir d'un coté un simple fichier de texte brut TODO qui reprend une liste "générique" des choses à faire, sans entrer réellement dans les détais (ou des bugs à résoudre, ou des modifications apportées, ...) et, de l'autre, utiliser les commandes dont j'ai parlé plus haut pour faire en sorte que doxygen génère automatiquement les listes plus fines ;)

C'est ce qui est déjà plus ou moins fait avec mon fichier CHANGELOGS.md
19/11/2013, 09h02
koala01
Citation:

Envoyé par Neckara

Les fichiers README.md sont par exemple directement affichés lorsqu'on affiche le dossier dans github.
Je trouve que c'est quand même assez pratique et cela permet aussi de soigner la mise en page.

Il ne sert à rien de trop se casser la tête non plus :

Le format markdown permet énormément de choses, et tu peux envisager de l'utiliser de nombreuses manières, mais tu dois veiller à séparer la fourniture de tes fichiers du reste du site de ton projet.

J'ai presque envie de dire (et je le dis d'ailleurs), le principe de la responsabilité unique s'applique tout aussi bien à tes outils d'intégration continue qu'à tes classes ou à tes fonctions.

Tu ne vas pas commencer à maintenir une liste de tous les bugs qui t'ont été remontés ni la liste de tous les commit effectué dans un fichier que tu fournis en même temps que ton projet: tu laisses cela à ton bugtracker ou à git lui-même!

Les fichiers que tu fournis sur ton gestionnaire de version concurrentes n'ont qu'un but : permettre à quelqu'un de télécharger ton code et de le compiler (plus ou moins) sans problème.

Tu dois donc te dire que tous les fichiers que tu vas transmettre sont destinés à être ouverts à l'aide d'un éditeur de texte basique, sans qu'il n'y ait la moindre mise en forme autre que celle que tu peux obtenir avec du texte brut.

Alors, bien sur, github a tendance à râler si tu ne places pas le fichier README.md (et peut etre le fichier LICENSE.md, je ne sais plus trop) à la racine du répertoire. Soit, autant le satisfaire, d'autant que ce sont des fichiers qui ne varient que très peu.

Mais pour le reste, un affichage qui "présente mieux" que du texte brut, ce n'est pas du ressort de ton gestionnaire de versions concurrentes!

C'est du ressort de ton site, de certains outils de génération automatique (comme doxygen) ou autre, mais, si les fichiers qui permettent cette génération peuvent être fournis en meme temps que le reste (c'est d'ailleurs préférable pour permettre à l'utilisateur de disposer de la doc sans devoir être forcément connecté à internet :D ), il n'y a aucune raison cohérente de décider de placer la documentation générée sur le gestionnaire de version.

Ce qui est du ressort de ton gestionnaire de versions, c'est:
- D'être en mesure de te dresser l'historique des modificatins
- D'être en mesure de te présenter le fichier dans l'état dans lequel il se trouve
- D'être en mesure de te présenter les différence entre deux versions du même fichier
Et, le tout, dans une forme proche du texte brut (même si cela n'en a peut etre que l'apparence parce que c'est malgré tout une page web qui t'es envoyée ;))

Or, j'ai l'impression que tu essayes de mélanger les différents éléments avec tes fichiers md :aie:

Dés lors, il ne faut pas vraiment s'étonner si, en utilisant plusieurs outils différents (mais permettant, en l'occurrence, d'obtenir un résultat fort identique), tu te retrouves confronté à des incompatibilités majeures :aie: :P

Citation:

J'utilise CMake (il est super utile \o/).

Le problème n'est pas le système utilisé pour la génération de Makefile, le problème est de savoir quels fichiers prendront du sens pour celui qui va télécharger ton projet.

Le format markdown (ou n'importe quel format utilisé pour la génération de documentation ou similaire) sera beaucoup plus contraignant à lire pour l'utilisateur que du simple texte brut étant donné que la première chose dont il dispose c'est... les fichiers qu'il vient de télécharger (ou d'extraire de l'archive qu'il vient de télécharger), et que tant que la documentation n'a pas été générée, il ne dispose, à la base, que d'un éditeur de texte.

Il est donc "logique" de faire en sorte que les fichiers dont il dispose et sur lesquels il va très certainement se ruer (README, LICENSE, INSTALL, ChangeLog et AUTHORS, si l'on en crois autotools :D) soient en texte brut plutôt qu'en texte formaté d'une quelconque manière ;)

Citation:

Au pire, je peux simplement faire un "mini-README" disant de générer la doc ou de regarder sur le dépôt github?

Je dirais plutôt de générer la doc ou de regarder sur le site (quitte à ce qu'il utilise le format markdown), mais oui.

Citation:

Disons que je trouve pratique de regrouper ces deux informations.
C'est un peu comme si je disais "ce qui va changer".

C'est, au contraire, tout sauf pratique!

Une documentation "pratique" est une documentation qui regroupe les informations par pertinence:

Si tu t'intéresse à ce qui doit être fait, tu dois pouvoir avoir la liste de toutes les choses à faire, point-barre. Tu n'as aucun besoin de savoir que telle chose à faire découle de tel changement effectué ;)

De toutes manières, si tu gères la liste des choses à faire à la main, la liste sera très vraisemblablement ordonnée "naturellement" par ordre d'apparition des choses à faire :D

Dans l'autre sens, si tu t'intéresses aux changements qui ont été apportés, tu n'as généralement que faire de la liste des choses à faire qui peut découler des changements en question ;)

En plus, je vois un inconvénient majeur à mélanger les deux:

La todo-list et la changelog-list évoluent de manière diamétralement opposée : généralement, la todo-list voit se faire retirer des items quand la changelog-list voit s'en faire rajouter.

Si tu mélanges les deux, tu auras très rapidement énormément de mal à retrouver une chose à faire particulière pour pouvoir la supprimer de ta liste, parce que tu devras commencer par te demander pour quel modification elle est apparue :aie: (en plus, il devient difficile de se faire une idée de la "somme de travail" à réaliser pour vider la todo-list :P)

Citation:

Je ne vais pas non-plus rajouter une ligne par issue résolue.
Mais je trouve pratique et encourageant de résumer ce qui a été fait quitte à résumer par la suite ce qui a été fait dans le mois par exemple.

Mais tu peux le faire en texte brut : une ligne par modification majeur, formatée de telle manière que tu saches plus ou moins quand cela a été fait.

Citation:

Par exemple, j'ai du faire une bonne 30ène de commit en deux jours.
Il est beaucoup plus simple pour moi de lire quelques lignes de changelogs que de relire mes commits.

Effectivement, le changelog et la liste des commits suivent deux objectifs totalement différents : la liste des commits permet de garder une trace beaucoup plus fine des changements que le changelog, parce que le but de la liste des commits est de pouvoir "revenir en arrière" en cas de besoin ;)

Attention, je ne dis pas que tu ne dois pas tenir le fichier changelog à jour, bien au contraire!

Je dis juste qu'il doit rester simple et ne contenir que des changements, rien d'autre.

Pour atteindre cet objectif, le plus facile est très certainement d'utiliser un format sous la forme de date : modification apportée et d'avoir une ligne par "éléments inscrit" ;)

Citation:

C'est ce qui est déjà plus ou moins fait avec mon fichier CHANGELOGS.md

Non, parce que tu mélanges allègrement la todolist et la changelist :aie:

En plus, comme je viens de le (re)préciser, le format md nécessite un traitement pour présenter quelque chose de "facilement compréhensible".

Or, ce traitement n'est disponible qu'au travers de l'interface de github (bon, allez, j'exagère un peu, mais tu comprends l'idée, hein?)!

En tout état de cause, ce traitement n'est, a priori, pas disponible pour celui qui vient de télécharger ton projet. (ou pour toi lorsque tu travailles sur ton projet ;))

Ce n'est donc pas le format qu'il te faut pour permettre à celui qui vient de récupérer les sources de se faire une idée de l'avancement du projet "hors connexion" ;)
19/11/2013, 09h51
Neckara

Citation:

Envoyé par koala01

Tu ne vas pas commencer à maintenir une liste de tous les bugs qui t'ont été remontés ni la liste de tous les commit effectué dans un fichier que tu fournis en même temps que ton projet: tu laisses cela à ton bugtracker ou à git lui-même!

Oui, je n'ai jamais dit que je souhaitais faire cela. :aie:

Citation:

Les fichiers que tu fournis sur ton gestionnaire de version concurrentes n'ont qu'un but : permettre à quelqu'un de télécharger ton code et de le compiler (plus ou moins) sans problème.

Tu dois donc te dire que tous les fichiers que tu vas transmettre sont destinés à être ouverts à l'aide d'un éditeur de texte basique, sans qu'il n'y ait la moindre mise en forme autre que celle que tu peux obtenir avec du texte brut.

N'est-il pas plus simple de le diriger vers la lecture de la page en ligne qui sera donc "mis en page" et ainsi théoriquement bien plus lisible ?
Exemple : la présence de liens et d'ancres.

Citation:

C'est du ressort de ton site, de certains outils de génération automatique (comme doxygen) ou autre, mais, si les fichiers qui permettent cette génération peuvent être fournis en meme temps que le reste (c'est d'ailleurs préférable pour permettre à l'utilisateur de disposer de la doc sans devoir être forcément connecté à internet :D ), il n'y a aucune raison cohérente de décider de placer la documentation générée sur le gestionnaire de version.

Attention, les fichiers markdown ne sont pas de la "documentation générée".
Ce sont des fichiers utilisés comme "sources" pour générer la documentation.
Et donc doivent être présent sur le dépôt pour être téléchargés.

Citation:

Dans l'autre sens, si tu t'intéresses aux changements qui ont été apportés, tu n'as généralement que faire de la liste des choses à faire qui peut découler des changements en question ;)

Ceci permet aussi de se resituer dans le contexte et de voir "où on en était".

Citation:

Si tu mélanges les deux, tu auras très rapidement énormément de mal à retrouver une chose à faire particulière pour pouvoir la supprimer de ta liste, parce que tu devras commencer par te demander pour quel modification elle est apparue :aie: (en plus, il devient difficile de se faire une idée de la "somme de travail" à réaliser pour vider la todo-list :P)

Non, car pour chaque ajout de "jour" dans le changelogs, je copie la TODO LIST puis je la met à jour.
En gros, j'ai pour chaque "jour" :
- ce que j'ai fait ;
- ce qu'il faudra que je fasse plus tard (le lendemain ou après).

Je peux donc rapidement voir ma progression.

Citation:

Or, ce traitement n'est disponible qu'au travers de l'interface de github (bon, allez, j'exagère un peu, mais tu comprends l'idée, hein?)!

En tout état de cause, ce traitement n'est, a priori, pas disponible pour celui qui vient de télécharger ton projet. (ou pour toi lorsque tu travailles sur ton projet ;))

Ce n'est donc pas le format qu'il te faut pour permettre à celui qui vient de récupérer les sources de se faire une idée de l'avancement du projet "hors connexion" ;)

Je peux alors le forcer à générer la documentation tout comme boost donne la doc (pour compiler/installer) sous forme html.
19/11/2013, 10h37
koala01
Citation:

Envoyé par Neckara

Oui, je n'ai jamais dit que je souhaitais faire cela. :aie:

J'espère bien !

C'étaient des exemples qui tendaient à démontrer que tu dois garder une responsabilité unique au niveau de tes outils :D

Citation:

N'est-il pas plus simple de le diriger vers la lecture de la page en ligne qui sera donc "mis en page" et ainsi théoriquement bien plus lisible ?
Exemple : la présence de liens et d'ancres.

En un mot : non!

D'abord, parce que ce que veut l'utilisateur, quand il vient d'obtenir les sources d'un projet, c'est du "quick start" : des documents simples qui permettent de répondre éventuellement à quelques questions comme :
1. comment je fais pour compiler?
2. La licence me permet elle l'usage que je prévois d'en faire?
3. Quelles sont les nouveautés par rapport à la version que j'ai (éventuellement)?
Ensuite, parce que ce n'est pas forcément parce que tes fichiers sont sur github que celui qui essaye de compiler ton projet dispose d'une connexion internet au moment de la compilation:

Il peut très bien avoir téléchargé les sources dans un cyber-café, ou les obtenir sur un CD avec un magasine quelconque, ou ... va savoir...

Tu peux fournir des liens en direction du site de ton projet, je ne dis pas le contraire, mais ca ne doit en aucun cas être la seule manière de disposer de la documentation, surtout pour l'approche en "quick start" ;)

Enfin, dés le moment où un fichier nécessite un traitement particulier afin de "présenter comme il se doit" -- et je parle aussi bien des commentaires doxygen que du format markdown ;) -- tu dois, ad minima, partir du principe que les informations qu'il contient ne sont accessibles qu'une fois une première étape franchie.

On est donc largement en dehors de l'aspect "quick start", vu que la première étape sera ... la compilation (la génération doxygen ou basée sur markdown n'étant qu'une sorte particulière de compilation ;))

Citation:

Attention, les fichiers markdown ne sont pas de la "documentation générée".
Ce sont des fichiers utilisés comme "sources" pour générer la documentation.
Et donc doivent être présent sur le dépôt pour être téléchargés.

Et tu n'as pas l'impression que cela fait un peu double emploi avec les sources doxygen :question:

Utilises tes fichiers markdown (ou du moins leur contenu) pour créer ton wiki si tu le souhaites, mais il ne sert à rien (il est même particulièrement dangereux) d'essayer de couvrir tout l'éventail des outils qui sont susceptibles de générer ta documentation : Dans le meilleur des cas, cela provoquera une duplication particulièrement dangereuse de tes informations :aie:

Pourquoi dangereuse me demanderas-tu sans doute :question: simplement parce qu'il arrivera systématiquement un moment où tu penseras à mettre une source de documentation à jour et pas l'autre.

En gros, c'est exactement le même problème que celui qu'on rencontre avec les commentaires qui paraphrasent le code ;)

Citation:

Ceci permet aussi de se resituer dans le contexte et de voir "où on en était".

YAGNI !

Citation:

If you don't need it, just don't do it

;)

Cette information t'intéresse peut être, mais elle n'intéresse très certainement pas celui qui veut compiler ton projet!

Si il veut savoir "ce qu'il reste à faire", il se foutra pas mal de savoir "depuis quand c'est sur la pile" ni "ce qui a été fait entre temps".

De la même manière, tu te rendras rapidement compte que tu n'as absolument pas besoin de savoir dans un même temps ce qui a été fait et ce qu'il reste à faire!

Soit, tu voudras te "remonter le moral" en pouvant te faire une idée du chemin parcouru, soit tu voudras savoir ce qu'il te reste à faire, histoire d'attaquer une des étapes.

Si tu mélanges systématiquement les deux, tu ne tarderas pas à te dire "C'est chouette, j'en suis là... Mais pfff... il me reste encore tout cela à faire."

Et cela ira exactement à l'encontre du but recherché en te démoralisant plus qu'autre chose ;)

Citation:

Non, car pour chaque ajout de "jour" dans le changelogs, je copie la TODO LIST puis je la met à jour.
En gros, j'ai pour chaque "jour" :
- ce que j'ai fait ;
- ce qu'il faudra que je fasse plus tard (le lendemain ou après).

Tu as besoin des deux informations, mais pas en même temps :
La todo-liste reprend les choses à faire, et est mise à jour chaque fois qu'une des choses à faire a été faite ou chaque fois qu'un nouvelle chose à faire apparait, et le changelog représente l'évolution du projet, ce qui a été fait et "validé" ;)

Il n'y a strictement aucun avantage à mélanger les deux, bien au contraire ! ;)

Citation:

Je peux donc rapidement voir ma progression.

Tu peux tout aussi facilement voir ta progression en ayant les informations dans des fichiers séparés! Et cela te démoralisera beaucoup moins ;)

Citation:

Je peux alors le forcer à générer la documentation tout comme boost donne la doc (pour compiler/installer) sous forme html.

Bien sur que tu peux parfaitement intégrer le processus de génération de documentation (quelque soit le moyen utilisé pour ce faire) dans ton processus global!

C'est même grandement conseillé :D

Mais, tu dois tenir compte du fait que, pour que la documentation soit utilisable, il faut passer par une étape qui n'a pas été franchie quand l'utilisateur vient tout juste de terminer le téléchargement / l'extraction de l'archive ;)
19/11/2013, 11h00
Neckara

Pour le quick start, je peux donc juste leur dire dans un README :
- lancez cmake : cmake . -G "Unix Makefiles" && make
- pour plus d'info générez la doc ;
- ou allez voir notre site, etc...

Citation:

Et tu n'as pas l'impression que cela fait un peu double emploi avec les sources doxygen :question:

Ben non.

Citation:

Utilises tes fichiers markdown (ou du moins leur contenu) pour créer ton wiki si tu le souhaites, mais il ne sert à rien (il est même particulièrement dangereux) d'essayer de couvrir tout l'éventail des outils qui sont susceptibles de générer ta documentation : Dans le meilleur des cas, cela provoquera une duplication particulièrement dangereuse de tes informations :aie:

Je n'ai jamais dit que je voulais faire un wiki :koi:
Dans le README, je donne les info de base ;
Dans CHANGELOGS, je met les modifications ;
Dans INSTALL, je dis comment compiler ;
Dans CONTACT, je dis comment nous contacter ;
Dans LICENCE, je donne la licence.
Ce sont en somme des informations de base non?

Citation:

Cette information t'intéresse peut être, mais elle n'intéresse très certainement pas celui qui veut compiler ton projet!

Au contraire, il sait ce qui a changé et les futures features à venir.

Citation:

Si il veut savoir "ce qu'il reste à faire", il se foutra pas mal de savoir "depuis quand c'est sur la pile" ni "ce qui a été fait entre temps".

Ben il regarde juste la dernière journée écrite.

Citation:

De la même manière, tu te rendras rapidement compte que tu n'as absolument pas besoin de savoir dans un même temps ce qui a été fait et ce qu'il reste à faire!

Soit, tu voudras te "remonter le moral" en pouvant te faire une idée du chemin parcouru, soit tu voudras savoir ce qu'il te reste à faire, histoire d'attaquer une des étapes.

Personnellement, pour le moment, je fais les deux en même temps.
J'ouvre le fichier CHANGELOGS et à chaque modifications/chaque chose faite, j'édite le CHANGELOGS en retirant l'entrée des choses à faire et je rajoute peut être une entrée dans le changelog.
19/11/2013, 11h29
koala01
Citation:

Envoyé par Neckara

Pour le quick start, je peux donc juste leur dire dans un README :
- lancez cmake : cmake . -G "Unix Makefiles" && make
- pour plus d'info générez la doc ;
- ou allez voir notre site, etc...

En gros, c'est l'idée ;)

Citation:

Ben non.

Et pourtant, si, à partir du moment où il est tout à fait possible de générer des pages quasiment similaire avec doxygen qu'avec le format markdown :D

Citation:

Je n'ai jamais dit que je voulais faire un wiki :koi:

Je sais bien, je te donnais un exemple concret d'utilisation du format markdown, rien de plus ;)

Citation:

Dans le README, je donne les info de base ;
Dans CHANGELOGS, je met les modifications ;
Dans INSTALL, je dis comment compiler ;
Dans CONTACT, je dis comment nous contacter ;
Dans LICENCE, je donne la licence.
Ce sont en somme des informations de base non?

Tout à fait.

Mais tu ne crois pas qu'un fichier de texte brut est tout aussi efficace et lisible :question:

Citation:

Au contraire, il sait ce qui a changé et les futures features à venir.

Si il s'intéresse à ce qui a changé, il ne s'intéresse pas forcément aux features à venir et, si il veut savoir ce que tu lui réserve pour la suite, il se fout pas mal de ce qui a déjà été fait ;)

Citation:

Personnellement, pour le moment, je fais les deux en même temps.
J'ouvre le fichier CHANGELOGS et à chaque modifications/chaque chose faite, j'édite le CHANGELOGS en retirant l'entrée des choses à faire et je rajoute peut être une entrée dans le changelog.

Tu te casses la tête pour rien!

Tu sais, personnellement, je m'en fous royalement que tu fasses à ta guise!

Mais ce que je trouve dommage, c'est que tu perdes ton temps à envisager une utilité qui est très loin d'être prouvée à une pratique inhabituelle, alors que tu as à ta disposition une vaste gamme de projet d'envergure pour te servir d'exemple et que -- à tord ou à raison -- tous ces projets vont au plus simple en ce qui concerne les changelog.

La plupart n'exposent d'ailleurs pas leur todo-list ailleurs qu'au niveau du "request tracker" (la partie du bugtracker qui permet de demander de nouvelles features ;))

Prend exemple sur l'existant, tu verras que le format utilisé est parfaitement adpaté au texte brut et qu'il permet même à certains outils (surtout sous linux :D ) d'en avoir une vision parfaitement user friendly.

Si l'on prend l'exemple de la plupart des projet GNU, le format du changelog est proche de
Code:

1 2 3 4 5 YYYY-MM-DD nom prenom <e-mail> * modification 1 * modification 2 * ... * modification N
Les premieres lignes du fichier étant les dernières modifications en date.

Simple et efficace! Et parfaitement lisible par l'humain en utilisant un simple éditeur de texte!

Pourquoi ne pas simplement décider de faire comme eux, au lieu de prendre le risque de te fourvoyer à vouloir mettre ton propre format au point :question:

D'autant plus que, comme je te l'ai dit plus tot, tu trouveras sans doute motivant le fait de voir d'où tu viens et où tu vas dans un premier temps, mais l'effet sera très certainement inversé d'ici peu, quand tu commenceras à avoir beaucoup plus de choses "dans le pipe" que de choses résolues ;)
23/11/2013, 14h35
Neckara

Merci pour tes réponses.

Pour le moment, je vais rester avec mes fichiers *.md et un README "minimal".

Si cela pose vraiment problème, j'aviserais mais je ne pense pas non plus que ce soit le plus important dans le dépôt (qui n'a pas encore toutes les sources :whistle:).

Je passe donc le sujet en résolu et je me remet au boulot ;)