Documentez votre projet avec les GitHub pages

Documentez votre projet avec les GitHub pages

Voyons cette semaine une fonctionnalité très pratique proposée par GitHub : les GitHub pages.

Les GitHub pages ?

Vous avez peut-être des projets (des repositories en fait) hébergés sur GitHub.
Ils comportent à coup sûr un fichier README.md pour expliquer comme l’installer et l’utiliser.

Mais quelques fois, une page ne suffit pas, et vous pouvez avoir besoin de créer une documentation sur plusieurs pages.

Il existe au moins deux solutions. La première : créer des pages de wiki.

La seconde, celle que nous allons voir dans cette article : vous pouvez associer la documentation au repository et la commiter dans une branche particulière (gh-pages) qui sera accessible à une adresse spécifique : https://<votre identifiant GitHub>.github.io/<nom du projet>/.

D’ailleurs il est aussi possible de créer un site Web statique associé à votre compte, en plus de ceux associés à vos projets.

La première fois

Créer la documentation

La documentation est composée de pages Web, donc de fichiers HTML, CSS, JavaScript, d’images, … A vous de créer ces pages avec votre méthode préférée.

Préparatifs

Créez d’abord un nouveau dossier, par exemple documentation-projet.

Clonez le projet que vous voulez documenter dans ce dossier :

git clone https://mon-projet-sur-github documentation-projet

Ensuite, dans le dossier documentation-projet, créez une nouvelle branche gh-pages :

git checkout -b gh-pages

Ce nom est reconnu par GitHub pour l’accès aux pages de documentation.

Ajouter les fichiers

Ensuite, supprimez tous les fichiers et tous les dossiers, à part .git bien sûr.

Cette suppression peut sembler bizarre, mais vous travaillez dans une branche, les fichiers de la branche ‘standard’ ne sont pas impactés.

Copiez à la place les fichiers HTML, CSS, … que vous avez créés au préalable.

Mise en ligne

Marquez les fichiers ajoutés, supprimés et modifiés :

git add --all .

Commitez localement :

git commit -m "Premier commit de la documentation"

Enfin, pushez la branche sur GitHub :

git push origin gh-pages

Une fois vos identifiants renseignés, le site est en ligne.

Les autres fois, pour modifier la documentation

Vous pouvez conserver le dossier qui existe déjà et travailler directement dedans.

Sinon vous devez cloner la branche de documentation.

Cloner la branche de documentation

Créez un nouveau dossier documentation-projet par exemple :

git clone https://mon-projet-sur-github documentation-projet

Ensuite, allez dans ce dossier.

Enfin, récupérez le contenu de la branche :

git checkout -b gh-pages origin/gh-pages

Mettre à jour la documentation

Dans tous les cas, c’est le moment de modifier la documentation.

Mise en ligne

Cette partie est identique à la création.

Marquez les fichiers à commiter :

git add --all .

Commitez :

git commit -m "Nouvelle version de la documentation"

Et enfin, pushez dans la branche gh-pages :

git push origin gh-pages

Et pour automatiser tout ça ?

Une fois la documentation créée, la mise à jour est plutôt facile.

Toutefois, il existe des générateurs de documentation, qui facilitent surtout l’étape de création des fichiers HTML, et automatisent le reste de la procédure.

D’ailleurs, j’en ai implémenté un en NodeJS, disponible avec NPM : Vegetables.

Le principe est simple : vous créez un dossier documentation dans le repository, vous écrivez la documentation au format Markdown, et en une ligne de commande les fichiers Markdown sont convertis en pages HTML à l’aide d’un template et envoyés dans la bonne branche sur GitHub.

Le mot de la fin

Documentez, c’est important ! En plus c’est facile.

L'illustration de cet article est une image sous licence CC BY-SA 4.0 par LaiaBT

Cet article vous a été utile ? Partage it !

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Si vous le souhaitez, renseignez le champ 'Nom' de cette façon : 'VotreNom@VotreMotClef' pour obtenir une ancre optimisée pour les moteurs de recherche.