Title: Les documentations cri et utilisateur pour l'ISIMA
Date: 2017-05-16 10:20
Status: Published
Tags: doc, mkdocs
[TOC]
## Pourquoi deux nouvelles documentations?
L'idée est de centraliser et surtout de mettre à jour les documentations existantes pour l'ISIMA
* [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 écrite 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 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
* <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-cri**](https://doc.cri.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-user**](https://doc.isima.fr/)
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é d'un compte Active Directory.
> 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/)
### 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é
* savoir ce qu'est [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 préserver l'installation système
#### Avec une copie locale du repo git (recommandée <i class="fa fa-thumbs-o-up" aria-hidden="true"></i>)
##### 1 - Récupérer les sources à partir de [https://gitlab.isima.fr](https://gitlab.isima.fr)
```bash
cd /path/to/your/projects/folder
git clone https://gitlab.isima.fr/cri/doc-cri
cd doc-cri
```
##### 2 - Démarrer l'environnement mkdocs local
```bash
mkdocs serve
```
[http://127.0.0.1:8000](http://127.0.0.1:8000) vous permet d'accéder au rendu de la doc en local
##### 3 - Créer ou éditer du contenu
###### 3.1 - Editer du contenu existant
* editer les fichiers [markdown (*.md)](https://guides.github.com/features/mastering-markdown/) dans le dossier ```docs```
* [atom.io](https://atom.io/) possède une coloration syntaxique et une prévisualisation pour [markdown](https://guides.github.com/features/mastering-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 - Ajouter du contenu
* créer un nouveau fichier markdown (.md) dans le dossier ```docs``` ou dans l'un de ses sous dossiers
* dans ```mkdocs.yml``` ajouter une entrée à la section ```page:``` afin d'ajouter le nouveau fichier au menu
* le nouveau fichier peut être ajouté à un sous menu
```yaml
pages:
- 'Section':
- 'Subsection': subsection.md
```
###### 3.3 - Versionner et propager les modifications
* Ajouter tous le nouveaux fichiers 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
```
<i class="fa fa-hand-peace-o" aria-hidden="true"></i> La documentation est automatiquement mise à jour à la suite de cette opération via l'intégration continue de gitlab !!
#### En modifiant directement sur le [<i class="fa fa-gitlab" aria-hidden="true"></i> gitlab de l'ISIMA](https://gitlab.isima.fr)
Sur toutes les pages de [**doc-cri**](https://doc.cri.isima.fr/) et [**doc-user**](https://doc.isima.fr/) vous retrouverez l'icône <i class="fa fa-pencil-square-o" aria-hidden="true"></i> qui vous permettra de modifier le contenu de la page en markdown directement dans [https://gitlab.isima.fr](https://gitlab.isima.fr).
[](images/cri/edit-gitlab.png)
> N.B. veillez à mettre un message explicite avant de cliquer sur le bouton "Commit Changes"
> N.B. à chaque fois que vous cliquerez sur le bouton "Commit Changes" un nouveau commit sera créé dans l'historique des modifications du repository. Pour des changements allant au delà de l'ajout de quelques lignes vous devriez [contribuer avec une copie locale du repo git](http://localhost:8000/les-documentations-cri-et-utilisateur-pour-lisima.html#avec-une-copie-locale-du-repo-git-recommandee)
## 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)