Title: Les documentations cri et utilisateur pour l'ISIMA et le LIMOS
Date: 2017-05-22 10:20
Status: Published
Tags: doc, python, mkdocs
Summary: Comment bien les utiliser, et comment y contribuer
Image: images/doc/book.jpg
[TOC]
## Pourquoi deux nouvelles documentations?
L'idée est de centraliser, tout en mettant à jour, les documentations existantes pour l'ISIMA et le LIMOS
* [http://com.isima.fr/cri/infoadmin](http://com.isima.fr/cri/infoadmin)
* [System Operations Center](http://192.168.100.7/PluXml/)
* [isima wiki / intranet](http://com.isima.fr/cri)
Si une autre source de documentation vous paraît pertinente n'hésitez pas à la soumettre à [cri@isima.fr](mailto:cri@isima.fr)
* la [documentation cri aka **doc-cri**](https://doc.cri.isima.fr/) est à usage restreint et nécessite donc une authentification avec le compte utilisateur Active Directory. Précisément elle est réservée aux seuls enseignants chercheurs ou personnels de l'ISIMA ou du LIMOS.
* la [documentation utilisateur aka **doc-user**](https://doc.isima.fr/) est consultable par tout un chacun.
## Comment sont faites ces deux documentations?
[doc-cri](https://doc.cri.isima.fr/) et [doc-user](https://doc.isima.fr/) sont toutes deux écrites avec le [projet MkDocs](http://www.mkdocs.org/),
issu du monde python et largement utilisé dans le monde de l'open source.
MkDocs]( est un module python qui permet à partir d'un code source (une simple arborescence de fichiers textes au format [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)) de générer des fichiers html statiques présentés dans une charte graphique fonctionnelle et unifiée.
Les codes source sont consultables et modifiables sur le [<i class="fa fa-gitlab" aria-hidden="true"></i>
gitlab de l'ISIMA](https://gitlab.isima.fr) par les seuls enseignants chercheurs ou personnels de l'ISIMA ou du LIMOS dotés d'un compte Active Directory.
* <i class="fa fa-gitlab" aria-hidden="true"></i>
[https://gitlab.isima.fr/cri/doc-user](https://gitlab.isima.fr/cri/doc-user) pour [**doc-user**](https://doc.isima.fr/)
* <i class="fa fa-gitlab" aria-hidden="true"></i>
[https://gitlab.isima.fr/cri/doc-cri](https://gitlab.isima.fr/cri/doc-cri) pour [**doc-cri**](https://doc.cri.isima.fr/)
> Toutes les contributions, corrections ou suggestions sont les bienvenues: **une documentation à jour est un gain de temps pour tous au quotidien!**
## Comment contribuer à [**doc-cri**](https://doc.cri.isima.fr/) ou à [**doc-user**](https://doc.isima.fr/)
### 0 - Prérequis
* [python](https://www.python.org/) >= 2.6 ([installation](http://www.mkdocs.org/#installing-python))
* [pip](https://pypi.python.org/pypi/pip) ([installation](https://pip.pypa.io/en/stable/installing/))
* [git](https://git-scm.com/) ([installation](https://git-scm.com/book/fr/v1/D%C3%A9marrage-rapide-Installation-de-Git))
* un éditeur de texte : [atom.io](https://atom.io/) est recommandé car il intègre un éditeur markdown ergonomique
* connaître les rudiments du *langage* [markdown](https://guides.github.com/features/mastering-markdown/)
* la commande [mkdocs](http://www.mkdocs.org/) installable via pip
```shell
sudo pip install mkdocs
```
> N.B. il est aussi possible d'installer mkdocs dans un virtualenv python afin de ne pas modifier la configuration de python sur votre système
### 1 - Récupérer les sources à partir de [https://gitlab.isima.fr](https://gitlab.isima.fr)
* forker le projet [https://gitlab.isima.fr/cri/doc-cri](https://gitlab.isima.fr/cri/doc-cri) ou [https://gitlab.isima.fr/cri/doc-user](https://gitlab.isima.fr/cri/doc-user)
[](images/cri/doc-cri.png)
* spécifier *éventuellement* l'utilisateur avec lequel forker
[](images/cri/fork-doc-cri-0.png)
* vous avez désormais un repository, clone de l'original, sur lequel vous pouvez travailler
[](images/cri/fork-doc-cri.png)
* vous pouvez cloner le repository en local
```bash
cd /path/to/your/projects/folder
git clone git@gitlab.isima.fr:mazenovi/doc-cri.git
cd doc-cri
```
### 2 - Démarrer l'environnement MkDocs local
```bash
mkdocs serve
```
* vous pouvez accéder à la doc en local en ouvrant [http://127.0.0.1:8000](http://127.0.0.1:8000) dans votre navigateur
### 3 - Éditer ou créer du contenu
#### 3.1 - Éditer du contenu existant
* éditer les fichiers markdown **(*.md)** dans le dossier ```docs```
* [atom.io](https://atom.io/) possède une coloration syntaxique et une prévisualisation pour markdown **(ctrl+maj+m)**
* les changements sont automatiquement rendus après sauvegarde du fichier sur [http://127.0.0.1:8000](http://127.0.0.1:8000)
#### 3.2 - Créer du contenu
* créer un nouveau fichier markdown (.md) dans le dossier ```docs``` ou dans l'un de ses sous dossiers
* [atom.io](https://atom.io/) possède une coloration syntaxique et une prévisualisation pour markdown **(ctrl+maj+m)**
* dans ```mkdocs.yml``` ajouter une entrée à la section ```page:``` afin d'ajouter le nouveau fichier au menu
> Attention tous les fichiers .md ajoutés doivent être référencés dans le fichier ```mkdocs.yml``` sans quoi ils ne seront pas interprétés
```yaml
pages:
- 'Section': section.md
```
* le nouveau fichier peut également être ajouté à un sous menu
```yaml
pages:
- 'Section':
- 'Subsection': subsection.md
```
* les changements sont automatiquement rendus après sauvegarde du fichier sur [http://127.0.0.1:8000](http://127.0.0.1:8000)
### 4 - Versionner et propager les modifications
* ajouter tous les nouveaux fichiers et les fichiers modifiés au prochain commit
```shell
git add . --all
```
* valider les modifications sur le repository git local via un commit
```bash
git commit -m "my awesome contribution"
```
* publier les modifications sur le repository git distant
```bash
git push origin master
```
* soumettre vos modifications via une **merge request** à partir de [https://gitlab.isima.fr](https://gitlab.isima.fr)
[](images/cri/merge-request-doc-cri-0.png)
* créer une nouvelle **merge request**
[](images/cri/merge-request-doc-cri-1.png)
* sélectionner la branche concernée (ici *master*) et cliquer sur **compare branches and continue***
[](images/cri/merge-request-doc-cri-2.png)
* ajouter la branche concernée (ici *master*) et cliquer sur **compare branches and continue***
[](images/cri/merge-request-doc-cri-3.png)
> Votre **merge request** sera automatiquement soumise à l'équipe CRI et mettra automatiquement la documentation à jour en cas d'acceptation
Pour en savoir plus sur git vous pouvez lire également mon post <a href="https://limos.isima.fr/~mazenod/git-101.html">git 101</a>
## Comment faire une demande d'ajout ou de modification
Vous pouvez adresser toutes vos demandes ou remarques en cliquant sur le lien "Issues"
[](images/cri/issue-gitlab.png)