IdentifiantMot de passe
Loading...
Mot de passe oublié ?Je m'inscris ! (gratuit)
Navigation

Inscrivez-vous gratuitement
pour pouvoir participer, suivre les réponses en temps réel, voter pour les messages, poser vos propres questions et recevoir la newsletter

C++ Discussion :

Doxygen : documentation de sous-projets


Sujet :

C++

  1. #1
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut 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" ?

  2. #2
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  3. #3
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    Merci, je vais tester ça dès que je le pourrais

  4. #4
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    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.

  5. #5
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    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.

  6. #6
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    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

  7. #7
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    Citation Envoyé par Neckara Voir le message
    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  8. #8
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    Merci pour tes réponses.

    Citation Envoyé par koala01 Voir le message
    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

  9. #9
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    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 : Sélectionner tout - Visualiser dans une fenêtre à part
    1
    2
    3
    4
    5
    /** @page page1 Le titre principal
       * 
       *  blahblah...
       * @ref section3
       */
    et pour un autre fichier
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  10. #10
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    En fait le problème, c'est que le fichier markdown est lu aussi bien par github que par doxygen

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

  11. #11
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    Ah, au fait,
    Citation Envoyé par Neckara Voir le message
    Je n'avais pas vu, c'est vraiment "caché" ça
    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 : Sélectionner tout - Visualiser dans une fenêtre à part
    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 : Sélectionner tout - Visualiser dans une fenêtre à part
    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  12. #12
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    Citation Envoyé par Neckara Voir le message
    En fait le problème, c'est que le fichier markdown est lu aussi bien par github que par doxygen

    Donc pour des ancres, je n'ai aucun problème, mais pour mettre un lien de fichier dans le fichier markdown...
    Excuses moi, mais comme je n'ai absolument aucune idée de ce que sont les fichier makdown dont tu me parle

    Pourrais tu m'en montrer un exemple, histoire que je sache à quoi je suis confronté
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  13. #13
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    En gros, c'est un fichier qui est ensuite "traduit" en HTML :

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

  14. #14
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    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

    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  15. #15
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    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".

  16. #16
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    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)

    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 : Sélectionner tout - Visualiser dans une fenêtre à part
    YYYY/MM/DD fixed issues #15 #17 and #495
    ou à
    Code : Sélectionner tout - Visualiser dans une fenêtre à part
    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

    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 ) -- Qu'est ce qui peut rester dans la documentation et qu'est-ce qui est intéressant d'exposer "par ailleurs"

    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

    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  17. #17
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    Citation Envoyé par koala01 Voir le message
    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.

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

    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?


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

    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.


    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

  18. #18
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    Citation Envoyé par Neckara Voir le message
    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 ), 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

    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
    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 ) soient en texte brut plutôt qu'en texte formaté d'une quelconque manière


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

    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 (en plus, il devient difficile de se faire une idée de la "somme de travail" à réaliser pour vider la todo-list )
    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.
    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"

    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

    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"
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

  19. #19
    Inactif  


    Homme Profil pro
    Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Inscrit en
    Décembre 2011
    Messages
    9 012
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 30
    Localisation : France, Loire (Rhône Alpes)

    Informations professionnelles :
    Activité : Doctorant sécurité informatique — Diplômé master Droit/Économie/Gestion
    Secteur : Enseignement

    Informations forums :
    Inscription : Décembre 2011
    Messages : 9 012
    Points : 23 209
    Points
    23 209
    Par défaut
    Citation Envoyé par koala01 Voir le message
    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.

    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.

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


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


    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 (en plus, il devient difficile de se faire une idée de la "somme de travail" à réaliser pour vider la todo-list )
    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.

    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.

  20. #20
    Expert éminent sénior
    Avatar de koala01
    Homme Profil pro
    aucun
    Inscrit en
    Octobre 2004
    Messages
    11 612
    Détails du profil
    Informations personnelles :
    Sexe : Homme
    Âge : 52
    Localisation : Belgique

    Informations professionnelles :
    Activité : aucun

    Informations forums :
    Inscription : Octobre 2004
    Messages : 11 612
    Points : 30 611
    Points
    30 611
    Par défaut
    Citation Envoyé par Neckara Voir le message
    Oui, je n'ai jamais dit que je souhaitais faire cela.
    J'espère bien !

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


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

    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

    Pourquoi dangereuse me demanderas-tu sans doute 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
    Ceci permet aussi de se resituer dans le contexte et de voir "où on en était".
    YAGNI !

    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

    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 !
    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
    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é

    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
    A méditer: La solution la plus simple est toujours la moins compliquée
    Ce qui se conçoit bien s'énonce clairement, et les mots pour le dire vous viennent aisément. Nicolas Boileau
    Compiler Gcc sous windows avec MinGW
    Coder efficacement en C++ : dans les bacs le 17 février 2014
    mon tout nouveau blog

+ Répondre à la discussion
Cette discussion est résolue.
Page 1 sur 2 12 DernièreDernière

Discussions similaires

  1. Récupérer documents privés sous XP
    Par arnaud_verlaine dans le forum Windows XP
    Réponses: 8
    Dernier message: 22/07/2006, 11h33
  2. notion de sous projet
    Par Abla23 dans le forum Zope
    Réponses: 4
    Dernier message: 04/07/2006, 12h49
  3. Document texte sous Oracle
    Par chiheb dans le forum Oracle
    Réponses: 7
    Dernier message: 24/10/2005, 17h33
  4. Imprimer un document publisher sous access
    Par alkmehd dans le forum Access
    Réponses: 2
    Dernier message: 22/09/2005, 13h25
  5. [eclipse 3.0.1] Création de projet avec sous-projet
    Par whilecoyote dans le forum Eclipse Java
    Réponses: 5
    Dernier message: 11/07/2005, 11h31

Partager

Partager
  • Envoyer la discussion sur Viadeo
  • Envoyer la discussion sur Twitter
  • Envoyer la discussion sur Google
  • Envoyer la discussion sur Facebook
  • Envoyer la discussion sur Digg
  • Envoyer la discussion sur Delicious
  • Envoyer la discussion sur MySpace
  • Envoyer la discussion sur Yahoo