Participer à la documentation Readthedocs¶

Au sein des équipes de Veremes, il arrive souvent que la documentation d’un produit ou d’un service se fasse par l’intermédiaire de Git et Readthedocs. Pour ce faire, il faut utiliser le format Markdown et écrire des fichiers qui seront publiés sur un dépôt Git ; ces derniers seront alors lus par Readthedocs, qui va publier la documentation au format sur le web HTML.

1. Les outils¶

Git¶

Pour commencer, il faudra au minimum installer Git et créer un compte sur le GitLab de Veremes. Ce qu’il faut comprendre de ces deux logiciels, c’est que Git s’installe sur un poste et permet de versionner des fichiers de manière à pouvoir voir quels ont été les derniers changements, revenir en arrière et faire plein d’autres choses très intéressantes ; quant à GitLab, c’est une plateforme web où on pourra visualiser et héberger tout ceci.

Atom¶

Il existe plusieurs logiciels permettant d’écrire au format Markdown ; en revanche, je conseille grandement Atom car il a été développé par les équipes de GitHub et qu’il permet une grande interaction avec Git ; de plus, en utilisant la commande ctrl + maj + M, on peut rapidement visionner ce que l’on écrit.

TortoiseGit¶

En option, si vous avez bien compris le fonctionnement de Git, il est intéressant d’utiliser TortoiseGit pour s’éviter de taper des lignes de commande quand on doit faire des choses compliquées.

2. Mise en place de l’environnement¶

Fork du projet¶

Si vous ne faites pas partie de l’équipe de développement de la documentation du produit, vous pouvez quand même effectuer des modifications puis demander à ce qu’elles soient appliquées. Si vous êtes membre du projet et que vous avez des droits en édition vous pouvez sauter cette étape.

Pour cela il faudra faire un Fork (ou “fourche”) du dépôt officiel vers votre compte en cliquant sur le bouton ../_images/documentation_fork_gitlab1.png Clone fork repo ou Clone fork repo fr

Maintenant GitLab vous demande où stocker le projet et c’est sur votre compte qu’il faudra le stocker.

../_images/documentation_fork_gitlab2.png Clone fork repo 2

Désormais le projet à été copié sur votre compte et vous avez tous les droits dessus car vous en êtes le propriétaire.

../_images/documentation_fork_gitlab3.png Clone fork repo 3

Clone¶

Pour éditer et créer des fichiers de documentation, il faudra clôner le dépôt sur lequel vous voulez travailler localement, ceci va créer une copie de ce dépôt dans un dossier de votre ordinateur. Pour cela, rendez-vous sur la page GitLab de Veremes du dépôt sur lequel vous voulez travailler, puis copiez l’adresse qui apparaît.

../_images/documentation_clone_gitlab.png Clone gitlab repo

Créez ensuite un répertoire sur votre poste où vous souhaitez stocker les dépôts ; si vous êtes sous Windows, faites un clic droit puis “Open Git bash here” ; si vous êtes sous Linux, rendez-vous simplement dans ce dossier. Maintenant que vous êtes sur votre terminal git, lancez une à une les commandes suivantes en prenant soin de remplacer votre adresse mail, votre nom ainsi que l’url par celle que vous avez copié précédemment.

git config --global user.email "you@example.com"

git config --global user.name "Your Name"

git clone http://vm09.veremes.net/Documentation/doc_app_vmap.git

Maintenant que vous avez rapatrié le dépôt chez vous, vous pouvez l’ouvrir avec l’éditeur Atom.

3. Travail sur le contenu des fichiers et envoi sur le serveur¶

Désormais que votre environnement est mis en place et que vous avez ouvert Atom sur le dossier qui vous intéresse, vous pouvez faire vos modifications en respectant la norme Markdown ; une fois vos modifications terminées, il faudra les valider puis les envoyer sur le serveur.

Avant toute chose, il faut être sûr que la version du dépôt située sur votre poste est bien à jour avec celle du serveur : peut-être que quelqu’un a fait des modifications entre-temps. Pour cela, il y a un bouton dédié sur Atom nous permettant de faire un Pull, c’est-à-dire rapatrier les modifications en local.

../_images/documentation_git_atom_0.png Fichiers modifiés git atom 0

Depuis Atom, vous avez peut-être remarqué que les fichiers ayant été modifiés ont changé de couleur depuis le bandeau de gauche :

../_images/documentation_git_atom_1.png Fichiers modifiés git atom 1

Cela signifie que vous pouvez, quand vous le souhaitez, valider vos modifications en effectuant un commit ; pour cela, utilisez le bouton symbolisant les fichiers à commiter situé en bas à droite de l’écran.

../_images/documentation_git_atom_2.png Fichiers modifiés git atom 2

Le menu suivant va apparaître sur l’écran ; depuis ce menu, vous pouvez visualiser les changements effectués en cliquant sur les fichiers et vous devrez placer les fichiers que vous voulez envoyer dans la partie Staged changes ; une fois que ceci est fait, il faudra écrire un commentaire décrivant les modifications que vous avez effectuées puis cliquer sur le bouton Commit.

../_images/documentation_git_atom_3.png Fichiers modifiés git atom 3

Maintenant que vous avez validé vos différentes modifications, il vous faudra les envoyer sur le serveur ; pour cela, utilisez le bouton Push.

../_images/documentation_git_atom_4.png Fichiers modifiés git atom 4

Désormais, vos modifications sont directement visibles sur l’interface GitLab du projet.

Demande de Merge¶

Si vous avez effectué un Fork du projet les modifications effectuées se situent sur le projet précédemment copié sous votre compte, pour que les modifications puissent être effectives sur le projet officiel, vous pouvez demander un merge aux administrateurs.

Pour cela cliquez sur le bouton New merge request:

../_images/documentation_merge_gitlab1.png Merge request 1

Sélectionnez la source et la destination puis lancez la comparaison des branches. Sur cet exemple nous avions modifiés le fichier Readme.md il apparaît donc sur l’interface

../_images/documentation_merge_gitlab2.png Merge request 2

Écrivez un titre à votre demande et cliquez sur le bouton Submit demande de fusion

../_images/documentation_merge_gitlab3.png Merge request 3

Votre merge a été demandé

../_images/documentation_merge_gitlab5.png Merge request 5

Fin¶

Désormais, vos modifications sont directement visibles sur l’interface GitLab du projet officiel, et si ce dernier est correctement lié à une page Readthedocs, il suffira de quelques minutes pour les voir apparaître sur la documentation en ligne.