La documentation générée doit-elle être stockée dans un référentiel Git?

49

Lorsque vous utilisez des outils tels que jsdocs , il génère des fichiers HTML statiques et leurs styles dans votre base de code en fonction des commentaires figurant dans votre code.

Ces fichiers doivent-ils être archivés dans le référentiel Git ou doivent-ils être ignorés avec .gitignore?

collecte des ordures
la source
4
Il peut y avoir un argument pour les stocker dans un dépôt GitHub que vous pouvez publier l'aide de HTML statiques pages . Bien que des arguments totalement distincts se présentent alors quant à la manière dont vous vous assurez qu'ils sont à jour, etc. ...
Boris the Spider
21
Si des fichiers sont générés, ils ne sont pas, par définition, source .
Chrylis
3
Vous publiez ce que vous voulez publier. Surtout sur GitHub. Si vous voulez que tout le monde voie un PDF ou une image générée, vous devez l'inclure au lieu d'attendre que tout le monde installe LaTeX et le compile eux-mêmes. Par exemple, ce référentiel ne serait pas très bon s'il n'incluait pas les images produites, mais uniquement les fichiers du projet ...
Džuris
7
En tant que consommateur de bibliothèques tierces, sur les 10 fois où je vois une bibliothèque sans documentation en ligne (que ce soit dans un sous-dossier du référentiel ou liée au fichier readme), je clique dessus et saute ces bibliothèques 10 fois. . Je ne vais pas me moquer de Doxygen pendant une demi-heure juste pour voir si une bibliothèque répond à mes besoins.
Alexander

Réponses:

131

En l'absence de besoin spécifique, aucun fichier pouvant être construit, recréé, construit ou généré à partir d'outils de construction à l'aide d'autres fichiers archivés dans le contrôle de version ne doit pas être archivé. Lorsque le fichier est requis, il peut être (re) construit à partir de l'autre. sources (et serait normalement comme un aspect du processus de construction).

Donc, ces fichiers doivent être ignorés avec .gitignore.

1201ProgramAlarm
la source
4
Mais cela peut dépendre des versions des outils de construction ou même de la disponibilité des outils de construction (par exemple, pour générer des fichiers, une ancienne version d’un outil de construction est nécessaire). Comment vas-tu prendre ça en charge? Pouvez-vous en parler dans votre réponse?
Peter Mortensen
27
@PeterMortensen Si vous avez besoin d'un artefact construit avec une version spéciale des outils buld, vous le créez avec la version des outils de construction dont vous avez besoin. Un tel besoin est soit a) découvert par vous-même, auquel cas vous êtes seul; b) documenté dans le fichier LISEZMOI ("Vous devez en avoir deux versions spécifiques de doxygen installées ..."); c) traités par les scripts de construction (ils vérifient les versions des outils de construction disponibles et agissent de manière appropriée). Dans tous les cas, le contrôle de source concerne les sources et non les artefacts de génération.
Joker_vD
2
Je pense que cette réponse n’est viable que si un serveur à déploiement continu construit et publie la documentation de manière facilement accessible. Autrement, il est très utile de "mettre en cache" les documents dans le référentiel pour améliorer l'accessibilité. Aucun utilisateur ne devrait avoir besoin de vos scripts de construction pour voir la documentation de votre logiciel.
Alexander
4
@ Alexandre Souhaitez-vous également mettre le binaire construit dans le repo? La documentation est construite. Vous prenez la documentation construite et la rendez accessible quelque part.
1201ProgramAlarm
5
@ 1201ProgramAlarm "Souhaitez-vous également mettre le binaire construit dans le référentiel?" Non, car un binaire construit a une faible valeur initiale pour les personnes parcourant GitHub, par rapport à la documentation. "Vous prenez la documentation construite et la rendez accessible quelque part." Tant que c'est hébergé publiquement, visiblement lié, alors oui, c'est génial. C'est probablement le meilleur des cas.
Alexandre
23

Ma règle est que lorsque je clone un référentiel et que j'appuie sur un bouton «build», tout est construit au bout d'un moment. Pour ce faire, vous avez le choix entre deux possibilités: soit quelqu'un est responsable de la création de ces documents et de leur mise dans git, soit vous documentez exactement le logiciel dont j'ai besoin sur ma machine de développement, et vous vous assurez que vous appuyez sur le bouton «build». Le bouton construit toute la documentation sur ma machine.

Dans le cas de la documentation générée, où toute modification apportée à un fichier d'en-tête devrait modifier la documentation, il est préférable de le faire sur la machine de chaque développeur, car je souhaite une documentation correcte à tout moment, pas seulement lorsqu'un utilisateur l'a mise à jour. Il existe d'autres situations dans lesquelles générer quelque chose peut prendre beaucoup de temps, être compliqué, nécessiter un logiciel pour lequel vous ne possédez qu'une licence, etc. Dans ce cas, il est préférable de confier à une personne la responsabilité de mettre les choses dans git.

@Curt Simpson: Avoir toutes les exigences logicielles documentées est bien meilleur que ce que j'ai vu dans de nombreux endroits.

gnasher729
la source
7
Ne pas documenter ce logiciel quelqu'un doit la construction (ou du moins ne pas tout document): faire le script de compilation indiquer à l'utilisateur ce qu'il manque ou même l' installer lui - même si c'est raisonnable. Dans la plupart de mes dépôts, tout développeur à moitié compétent peut simplement exécuter ./Testet obtenir une version ou obtenir de bonnes informations sur ce qu'il doit faire pour obtenir une version.
Curt J. Sampson
5
Je ne suis pas vraiment d'accord pour dire que mettre de la documentation générée dans git peut être utile dans le cas que vous spécifiez. C'est la raison pour laquelle nous avons des artefacts et des archives.
Sulthan
C'est votre règle et c'est une bonne règle et j'aime bien. Mais d'autres peuvent créer leurs propres règles.
emory
Je pense que vous voulez dire "exécuter une commande de compilation", car il n'y aurait pas de bouton de compilation sur votre machine. ... Sauf si vous vous attendez à ce que toute la construction soit intégrée à un IDE, ce qui est totalement déraisonnable.
jpmc26
@ jpmc26 Je trouve totalement raisonnable d'intégrer l'intégralité de la construction dans un IDE. Le bouton de compilation de ma machine est Command-B.
gnasher729
14

Ces fichiers ne doivent pas être archivés car les données pour les générer sont déjà présents. Vous ne voulez pas stocker les données deux fois (DRY).

Si vous avez un système CI, vous pourriez peut-être créer cette documentation et la stocker pour cette construction / publication sur un serveur Web.

Tvde1
la source
4

L’avantage de les avoir dans certains référentiels (identiques ou différents, de préférence générés automatiquement), c’est que vous pouvez voir toutes les modifications apportées à la documentation. Parfois, ces diffs sont plus faciles à lire que les diffs du code source (en particulier si vous vous souciez uniquement des modifications de spécification, et non de la mise en œuvre).

Mais dans la plupart des cas, les avoir dans le contrôle de code source n'est pas nécessaire, comme l'expliquent les autres réponses.

Paŭlo Ebermann
la source
1
Cela nécessiterait quasiment un hook de pré-commit dans chaque dépôt utilisé pour créer des commits. Parce que si le processus de génération de documentation n'est pas entièrement automatisé, vous obtiendrez des validations dont la documentation ne serait pas synchronisée avec le code. Et ces commits cassés vont nuire à la compréhensibilité plus que la documentation non validée.
cmaster
1
Cela ne doit pas nécessairement être au stade de la validation. Cela pourrait facilement être un travail en aval / CI / Jenkins de les publier chaque fois qu'ils méritent d'être stockés. Ce peut être bien chaque engagement, mais la décision devrait être découplée en l'absence d'une bonne raison. Ou du moins c'est comme ça que je le vois.
Une personne
3

Ignoré. Vous souhaiterez de toute façon que les utilisateurs du référentiel puissent les reconstruire, ce qui évite d'avoir à s'assurer que les documents sont toujours synchronisés. Il n'y a aucune raison de ne pas regrouper les artefacts construits au même endroit si vous voulez tout avoir au même endroit et ne pas avoir à construire quoi que ce soit. Cependant, les dépôts de source ne sont pas vraiment un bon endroit pour le faire, car la complexité y nuit plus que la plupart des endroits.

Une
la source
2

Cela dépend de votre processus de déploiement. Cependant, la validation des fichiers générés dans un référentiel est une exception et doit être évitée, si possible. Si vous pouvez répondre aux deux questions suivantes avec Oui , l’archivage de vos documents peut être une option valide:

  • Les documents sont-ils une exigence pour la production?
  • Votre système de déploiement manque-t-il des outils nécessaires pour construire les documents?

Si ces conditions sont remplies, vous déployez probablement avec un système hérité ou un système avec des contraintes de sécurité particulières. Au lieu de cela, vous pouvez valider les fichiers générés dans une branche de publication et maintenir la branche principale propre.

Trendfischer
la source
1
La validation des fichiers générés dans une branche de publication ne fonctionne pas dans toutes les situations, mais il en existe plusieurs, en particulier pour des sites Web statiques construits à partir de markdown, où cette solution est excellente. Je le fais assez souvent pour construire un outil spécial permettant de générer facilement de tels commits dans le cadre du processus de construction.
Curt J. Sampson
2

Ça dépend. Si ces docs:

  • Doit faire partie du référentiel, comme le readme.md, alors il est préférable de les conserver dans le dépôt git. Parce qu'il peut être difficile de gérer ces situations de manière automatisée.

  • Si vous ne disposez pas d'un moyen automatisé de les construire et de les mettre à jour, comme un système CI, et qu'il est destiné à être vu par le grand public, il est préférable de les conserver dans le référentiel git.

  • Il faut BEAUCOUP de temps pour les construire, alors il est légitime de les conserver.

  • Sont destinés à être vus pour le grand public (comme le manuel d'utilisation), et cela prend un temps considérable à construire, alors que vos documents précédents deviennent inaccessibles (hors ligne), il est alors justifiable de les conserver dans le dépôt git.

  • Sont destinés à être vus par le grand public et doivent montrer un historique de ses changements / évolutions, il pourrait être plus facile de garder les versions précédentes du document engagées et de construire / engager la nouvelle version liée à la précédente. Justifiable.

  • A une raison acceptée spécifique pour que toute l'équipe soit engagée, il est alors justifiable de les garder dans le dépôt Git. (Nous ne connaissons pas votre contexte, votre équipe et vous le savez)

Dans tout autre scénario, il devrait être ignoré en toute sécurité.

Toutefois, s’il est justifié de les conserver dans le dépôt git, cela pourrait indiquer un autre problème plus important auquel votre équipe est confrontée. (Ne pas avoir un système de CI ou des problèmes de performance similaires, horribles, faire face aux temps morts pendant la construction, etc.)

throawableAccount2892391
la source
1

En tant que principe de contrôle de version, seuls les "objets primaires" doivent être stockés dans un référentiel, pas les "objets dérivés".

Il existe des exceptions à la règle: à savoir, lorsque des utilisateurs du référentiel ont besoin des objets dérivés et que l'on peut raisonnablement s'attendre à ce qu'ils ne disposent pas des outils nécessaires pour les générer. D'autres considérations entrent en ligne de compte, comme est la quantité de matériau difficile à manier? (Serait-il préférable que le projet demande à tous les utilisateurs de disposer des outils?)

Un exemple extrême de ceci est un projet qui implémente un langage de programmation rare dont le compilateur est écrit dans ce langage lui-même (des exemples bien connus incluent Ocaml ou Haskell) Si seul le code source du compilateur est dans le référentiel, personne ne peut le construire. ils ne disposent pas d'une version compilée du compilateur qu'ils peuvent exécuter sur la machine virtuelle afin de pouvoir compiler le code source de ce compilateur. De plus, les dernières fonctionnalités du langage sont immédiatement utilisées dans le source du compilateur lui-même, de sorte qu'il est toujours nécessaire de s'approcher de la dernière version du compilateur pour le compiler: un exécutable de compilateur vieux d'un mois obtenu séparément ne compilera pas le code actuel utilise des fonctionnalités de langage qui n'existaient pas il y a un mois. Dans cette situation, la version compilée du compilateur doit presque certainement être archivée dans le référentiel et mise à jour.

Kaz
la source