Newer
Older
Title: Les documentations cri et utilisateur pour l'ISIMA
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.
[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/)
* [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
```
> 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
```
[http://127.0.0.1:8000](http://127.0.0.1:8000) vous permet d'accéder au rendu de la doc en local
* 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)
* 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
```
* 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)
Vous pouvez adresser toutes vos demandes ou remarques en cliquant sur le lien "Issues"
[](images/cri/issue-gitlab.png)