enhance doc post

content/cri/documentation.md

-Title: Les documentations cri et utilisateur pour l'ISIMA
-Date: 2017-05-16 10:20
+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 et surtout de mettre à jour les documentations existantes pour l'ISIMA
+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/)
@@ -15,79 +17,96 @@ L'idée est de centraliser et surtout de mettre à jour les documentations exist
 
 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.
+* 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/),
+[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 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.
+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.
 
-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-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/)
 
- 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
+> 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
+### 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é
-* savoir ce qu'est [markdown](https://guides.github.com/features/mastering-markdown/)
+* 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 préserver l'installation système
+> 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)
+
+[![fork doc-cri step 1](images/cri/doc-cri.png)](images/cri/doc-cri.png)
 
-#### Avec une copie locale du repo git (recommandée <i class="fa fa-thumbs-o-up" aria-hidden="true"></i>)
+* spécifier *éventuellement* l'utilisateur avec lequel forker
 
-##### 1 - Récupérer les sources à partir de [https://gitlab.isima.fr](https://gitlab.isima.fr)
+[![fork doc-cri step 2](images/cri/fork-doc-cri-0.png)](images/cri/fork-doc-cri-0.png)
+
+* vous avez désormais un repository, clone de l'original, sur lequel vous pouvez travailler
+
+[![fork doc-cri step 3](images/cri/fork-doc-cri.png)](images/cri/fork-doc-cri.png)
+
+* vous pouvez cloner le repository en local
 
 ```bash
 cd /path/to/your/projects/folder
-git clone https://gitlab.isima.fr/cri/doc-cri
+git clone git@gitlab.isima.fr:mazenovi/doc-cri.git
 cd doc-cri
 ```  
 
-##### 2 - Démarrer l'environnement mkdocs local
+### 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
 
-[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 - &Eacute;diter ou créer du contenu
 
-##### 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)**
+#### 3.1 - &Eacute;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 - Ajouter du contenu
+#### 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
-    * le nouveau fichier peut être ajouté à un sous 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:
@@ -95,36 +114,47 @@ pages:
         - 'Subsection': subsection.md
 ```
 
-###### 3.3 - Versionner et propager les modifications
+* les changements sont automatiquement rendus après sauvegarde du fichier sur [http://127.0.0.1:8000](http://127.0.0.1:8000)
 
-* Ajouter tous le nouveaux fichiers au prochain commit
+### 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
+* 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
+* 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)
+* soumettre vos modifications via une **merge request** à partir de [https://gitlab.isima.fr](https://gitlab.isima.fr)
+
+[![merge request doc-cri step 0](images/cri/merge-request-doc-cri-0.png)](images/cri/merge-request-doc-cri-0.png)
+
+* créer une nouvelle **merge request**
+
+[![merge request doc-cri step 1](images/cri/merge-request-doc-cri-1.png)](images/cri/merge-request-doc-cri-1.png)
+
+* sélectionner la branche concernée (ici *master*) et cliquer sur **compare branches and continue***
+
+[![merge request doc-cri step 2](images/cri/merge-request-doc-cri-2.png)](images/cri/merge-request-doc-cri-2.png)
 
-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).
+* ajouter la branche concernée (ici *master*) et cliquer sur **compare branches and continue***
 
-[![Edit via gitlab](images/cri/edit-gitlab-thumb.png)](images/cri/edit-gitlab.png)
+[![merge request doc-cri step 3](images/cri/merge-request-doc-cri-3.png)](images/cri/merge-request-doc-cri-3.png)
 
-> N.B. veillez à mettre un message explicite avant de cliquer sur le bouton "Commit Changes"
+> Votre **merge request** sera automatiquement soumise à l'équipe CRI et mettra automatiquement la documentation à jour en cas d'acceptation
 
-> 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)
+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
 

content/extra/custom.css

@@ -36,3 +36,8 @@ img.logo {
 ul.list-group-flush>li.list-group-item{
     border-bottom: 1px solid #DCE4EC;
 }
+
+article img {
+    border: 1px solid #eeeeee;
+    border-radius: 10px;
+}

content/gitlab/gitlab.md

@@ -7,7 +7,7 @@ Tags: www, dev
 
 ## Ce que n'est pas gitlab ...
 
-Un substitut de Dropbox! Gitlab est optimisé pour versionner des fichiers textes, d'une taille raisonnable ...
+Un substitut de Dropbox! Gitlab est optimisé pour versionner des fichiers textes, d'une taille raiisonnable ...
 Eviter donc les dossiers de milliers d'images, les vidéos de plusieurs giga
 
 
@@ -16,6 +16,10 @@ Eviter donc les dossiers de milliers d'images, les vidéos de plusieurs giga
 * simplification de l'administration (private/internal/publi) plutôt que de constituer une équipe nominativement
 * les groupes en mode super utilisateurs
 
+## configurer ses clés ssh
+
+## mattermost
+
 ### Merge requests
 
 ### Intégration continue

content/images/doc/.comments/book.jpg.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<comment version="3.0">
+  <caption/>
+  <note>Red hardcover book gutter with sewn pages flipping through the air ready for browsing. The cover has a shiny, plastic texture.</note>
+  <place/>
+  <categories>
+    <category value="gutter"/>
+    <category value="pages"/>
+    <category value="hardcover"/>
+    <category value="book"/>
+  </categories>
+</comment>

content/tech/git.md

@@ -45,3 +45,7 @@ http://themouette.github.io/slides-git/?theme=clermontech#/
 https://speakerdeck.com/willdurand/git-and-github-and-open-source-clermontech-workshop-git
 
 ### GUI
+
+### .gitconfig
+
+* melf mergetool difftool

content/tech/markdown.md

@@ -5,6 +5,8 @@ Tags: www, dev
 
 ## Qu'est ce que markdown?
 
+* http://www.aaronsw.com/weblog/001189
+
 * https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
 
 ## Pourquoi markdown?

themes/limos/templates/article_list.html

@@ -2,17 +2,28 @@
 {% block content %}
     {% if articles %}
         {% for article in (articles_page.object_list if articles_page else articles) %}
-            <article>
-                <h2><a href="{{ SITEURL }}/{{ article.url }}">{{ article.title }}</a></h2>
-                {% if DISPLAY_ARTICLE_INFO_ON_INDEX %}
-                    <div class="well well-sm">
-                        {% include "includes/article_info.html" %}
-                    </div>
+            <article class="row">
+                {% if article.image %}
+                <div class="col-lg-8">
+                {% else %}
+                <div class="col-lg-12">
                 {% endif %}
-                <div class="summary">{{ article.summary }}
-                    {% include 'includes/comment_count.html' %}
-                    <a class="btn btn-default btn-xs" href="{{ SITEURL }}/{{ article.url }}">{{ _('more') }} ...</a>
+                    <h2><a href="{{ SITEURL }}/{{ article.url }}">{{ article.title }}</a></h2>
+                    {% if DISPLAY_ARTICLE_INFO_ON_INDEX %}
+                        <div class="well well-sm">
+                            {% include "includes/article_info.html" %}
+                        </div>
+                    {% endif %}
+                    <div class="summary">{{ article.summary }}
+                        {% include 'includes/comment_count.html' %}
+                        <a class="btn btn-default btn-xs" href="{{ SITEURL }}/{{ article.url }}">{{ _('more') }} ...</a>
+                    </div>
                 </div>
+                {% if article.image %}
+                <div class="col-lg-4">
+                    <img src="{{ SITEURL }}/{{ article.image }}" class="img-responsive" />
+                </div>
+                {% endif %}
             </article>
             <hr/>
         {% endfor %}