# 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](https://guides.github.com/features/mastering-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](https://git-scm.com/) et créer un compte sur le [GitLab de Veremes](http://vm09.veremes.net). 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](https://atom.io/) 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  ou  Maintenant GitLab vous demande où stocker le projet et c'est sur votre compte qu'il faudra le stocker.  Désormais le projet à été copié sur votre compte et vous avez tous les droits dessus car vous en êtes le propriétaire.  ### 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](http://vm09.veremes.net) du dépôt sur lequel vous voulez travailler, puis copiez l'adresse qui apparaît.  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](https://guides.github.com/features/mastering-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.  Depuis Atom, vous avez peut-être remarqué que les fichiers ayant été modifiés ont changé de couleur depuis le bandeau de gauche :  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.  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**.  Maintenant que vous avez validé vos différentes modifications, il vous faudra les envoyer sur le serveur ; pour cela, utilisez le bouton **Push**.  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*:  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  Écrivez un titre à votre demande et cliquez sur le bouton *Submit demande de fusion*  Votre merge a été demandé  ### 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.