Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# 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 la commande suivante
en prenant soin de remplacer l'url par celle que vous avez copié précédemment.
```
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.