Generer et deployer automatiquement de la documentation grâce à wercker

Catégorie: Hébergement (Mis à jour le 13-03-2016 20:33:45)

Plus un projet est gros, plus la qualité de la documentation est importante.

Heureusement, aujourd'hui on dispose d'outils pour générer de la documentation sur le code de façon automatique. Cela permet de gagner du temps en integrant directement cette documentation dans le code correspondant. En plus, grâce aux services de déploiement continu, on peux à chaque push de nouveau code générer la nouvelle documentation et la publier pour tous nos developpeurs de façon automatique et sans intervention manuelle.

Le but de cet article est de proposer une approche pour gagner du temps en automatisant à la fois la rédaction de documentation, mais aussi sa publication et sa diffusion au sein d'une équipe. Cette documentation sera rédigée via les commentaires phpDoc, puis mise en ligne automatiquement à chaque nouveau commit sur le dépot git.

Technologies

Dans la suite, la documentation sera générée via phpDoc. Si vous utilisez un autre language, cherchez un système qui propose un fonctionnement similaire (Javadoc par exemple).

La documentation sera stockée sur un second dépôt git. Cela permet de traiter la documentation de façon similaire au code et de ne pas perdre nos développeurs s'ils doivent en rédiger une partie a la main. Et puis vu qu'on versionne notre code, pourquoi ne pas aussi versionner la documentation.

Le fonctionnement

Notre système fonctionne en deux phases: d'abord on génére la documentation, puis on publie cette nouvelle version à la place de l'ancienne.

Personnellement, j'utilise wercker. Je le fais tourner sur ma branche master pour avoir la doc des versions stables de mon projet.

Voici donc le script qui me sert à déployer ma doc sur un dépôt bitbucket:

Le code et la structure sont simples et la démarche est adaptable pour travis (contributions welcome).

En conclusion

Grâce à ce système, notre documentation est toujours synchronisée avec la dernière version stable du code.

Cela ne remplace hélas pas la rédaction manuelle de doc qui doit toujours être faite mais cela permet sa publication et sa diffusion de manière automatique et systématique.

Pour donner des pistes d'améliorations, on peux aussi coupler le dépôt qui conserve la doc avec un serveur web afin d'avoir une version à jour directement disponible pour vos développeurs ou vos clients.

A lire aussi:

Comparaison et avis sur les hébergements PHP gratuits

[Hébergement] Developper son site c'est bien, mais il ne sert à rien sur votre disque dur. Voici une liste qui vous permettra de choisir le meilleur hebergement gratuit pour votre production.
Suite...

Augmentez gratuitement la capacité de votre site avec cloudflare

[Hébergement] Votre site commence à devenir populaire et votre serveur ne suffit plus? Réduisez la charge de votre site gratuitement avec un CDN tel que Cloudflare.
Suite...