# 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
![Clone fork repo](images/documentation_fork_gitlab1.png) ou
![Clone fork repo fr](images/documentation_fork_gitlab1_1.png)

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

![Clone fork repo 2](images/documentation_fork_gitlab2.png)

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

![Clone fork repo 3](images/documentation_fork_gitlab3.png)

### 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.

![Clone gitlab repo](images/documentation_clone_gitlab.png)

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.

![Fichiers modifiés git atom 0](images/documentation_git_atom_0.png)

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

![Fichiers modifiés git atom 1](images/documentation_git_atom_1.png)

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.

![Fichiers modifiés git atom 2](images/documentation_git_atom_2.png)

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**.

![Fichiers modifiés git atom 3](images/documentation_git_atom_3.png)

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

![Fichiers modifiés git atom 4](images/documentation_git_atom_4.png)

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*:

![Merge request 1](images/documentation_merge_gitlab1.png)

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

![Merge request 2](images/documentation_merge_gitlab2.png)

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

![Merge request 3](images/documentation_merge_gitlab3.png)

Votre merge a été demandé

![Merge request 5](images/documentation_merge_gitlab5.png)


### 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.