documentation.md

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

• Pourquoi deux nouvelles documentations?
• Comment sont faites ces deux documentations?
• Comment contribuer à doc-cri ou à doc-user
  • 0 - Prérequis
  • 1 - Récupérer les sources à partir de https://gitlab.isima.fr
  • 2 - Démarrer l'environnement MkDocs local
  • 3 - Éditer ou créer du contenu
    • 3.1 - Éditer du contenu existant
    • 3.2 - Créer du contenu
  • 4 - Versionner et propager les modifications
• Comment faire une demande d'ajout ou de modification

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
• System Operations Center
• isima wiki / intranet

Si une autre source de documentation vous paraît pertinente n'hésitez pas à la soumettre à cri@isima.fr

• la documentation cri aka doc-cri 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 est consultable par tout un chacun.

Comment sont faites ces deux documentations?

doc-cri et doc-user sont toutes deux écrites avec le projet MkDocs, 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) 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 gitlab de l'ISIMA par les seuls enseignants chercheurs ou personnels de l'ISIMA ou du LIMOS dotés d'un compte Active Directory.

• https://gitlab.isima.fr/cri/doc-user pour doc-user
• https://gitlab.isima.fr/cri/doc-cri pour doc-cri

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 ou à doc-user

0 - Prérequis

• python >= 2.6 (installation)
• pip (installation)
• git (installation)
• un éditeur de texte : atom.io est recommandé car il intègre un éditeur markdown ergonomique
• connaître les rudiments du langage markdown
• la commande mkdocs installable via pip

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

• forker le projet https://gitlab.isima.fr/cri/doc-cri ou https://gitlab.isima.fr/cri/doc-user

• spécifier éventuellement l'utilisateur avec lequel forker

• vous avez désormais un repository, clone de l'original, sur lequel vous pouvez travailler

• vous pouvez cloner le repository en local

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

mkdocs serve

• vous pouvez accéder à la doc en local en ouvrant 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 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

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 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

pages:
    - 'Section': section.md

• le nouveau fichier peut également être ajouté à un sous menu

pages:
    - 'Section':
        - 'Subsection': subsection.md

• les changements sont automatiquement rendus après sauvegarde du fichier sur 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

git add . --all

• valider les modifications sur le repository git local via un commit

git commit -m "my awesome contribution"

• publier les modifications sur le repository git distant

git push origin master

• soumettre vos modifications via une merge request à partir de https://gitlab.isima.fr

• créer une nouvelle merge request

• sélectionner la branche concernée (ici master) et cliquer sur compare branches and continue*

• ajouter la branche concernée (ici master) et cliquer sur compare branches and continue*

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 git 101

Comment faire une demande d'ajout ou de modification

Vous pouvez adresser toutes vos demandes ou remarques en cliquant sur le lien "Issues"