documentation.md

Title: Les documentations cri et utilisateur pour ISIMA/LIMOS Date: 2017-05-16 10:20 Status: Published Tags: doc, admin, www

$e=mc^2$

La doc cri et la doc user de l'ISIMA/LIMOS sont toutes les deux rédigées avec le projet MkDocs. mkdocs permet de générer une documenation html statique à partir de simples fichiers textes au format markdown.

L'idée est de centraliser et surtout de mettre à jour les documentations historiques

• http://com.isima.fr/cri/infoadmin
• System Operations Center
• isima wiki / intranet

La doc cri est à usage restreint et nécessite donc une authentification avec le compte utilisateur Active Directory.

Tous les membres de l'ISMA et du LIMOS sont invités à contribuer à ces documentations via les repository git dédiés sur https://gitlab.isima.fr

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

Modifier la documentation doc cri ou doc user

1.Installer l'environnement

Prérequis

• python >= 2.6 (installation)
• pip (installation)
• git (installation)
• un éditeur de texte : atom.io est recommandé
• savoir ce qu'est markdown
• la commande mkdocs installable via pip

sudo pip install

N.B. il est aussi possible d'installer mkdocs dans un virtualenv python afin de préserver l'installation système

2. récupérer les sources à partir de https://gitlab.isima.fr

cd /path/to/your/projects/folder
git clone https://gitlab.isima.fr/cri/doc-cri
cd doc-cri

3. démarrer l'environnement local

mkdocs serve

• ourvir http://127.0.0.1:8000 dans votre navigateur

4. créer ou éditer du contenu

4.1 éditer du contenu

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

4.2 ajouter du contenu

1. créer un nouveau fichier markdown (.md) dans le dossier docs ou dans l'un de ses sous dossiers

un fichier template.md est diponible directement dasn le dossier doc

l'architecture des sous dossiers devrait suivre l'architecture du menu général mentionné ci-après

2. dans mkdocs.yml

3. ajouter une entrée à la section page: afin d'ajouter le nouveau fichier au menu * le nouveau fichier peut être ajouté à un sous menu

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

6. Versionner et propager les modifications

• Ajouter tous le nouveaux fichiers 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

La documentation est automatiquement mise à jour à la suite de cette opération !!

mkdocs
atom preview
git add . --all
git commit -m "message explicite"
git commit --amend
git push origin master
git status
git pull --rebase
git statsh
git apply

Faire une demande de documentation

Avec un virtualenv (c'est à dire en utilisant une installation isolée de l'OS )

Vérifiez si vous avez virtualenv déjà installé:

$ python -m venv usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] ENV_DIR [ENV_DIR ...] venv: error: the following arguments are required: ENV_DIR

Si cette commande ne marche pas, il faudra installer virtualenv:

pip install --user virtualenv

Si vous avez besoin d’un rappel sur pip, c’est par là.

Ensuite, pour chacun de vos projets, créez un environnement virtuel, avec:

python -m venv /path/vers/projet/env_nom_du_projet

Si vous l’aviez déjà. Ou:

virtualenv /path/vers/projet/env_nom_du_projet

Choisir une version de Python

Parfois vous voudrez utiliser une version spécifique de Python. Vous pouvez tout à fait créer un env dédié à Python 3.2 et un autre à Python 2.6, il faut juste que les deux versions soient installées sur votre système.

Je ne vais pas détailler commen installer deux versions de Python en parallèle sur chaque OS car je n’ai aucune idée de comment on fait sous Mac ou Windows, mais sous Ubuntu c’est très simple: par défaut on est en Python 2.7, et pour installer Python 3, on fait sudo apt-get install python3. Pour installer Python 2.6, on fait sudo apt-get python2.6.

On a alors 3 executables: /usr/bin/python va déclencher Python 2.7, /usr/bin/python2.6 va appeler Python 2.6, etc. Aucun conflit système, c’est merveilleux.

Il ne reste qu’à construire son environnement virtuel en lui passant en paramètre le chemin vers le Python à utiliser:

virtualenv mon_env -p /usr/bin/python2.6

Si vous êtes sous Windows, vous pouvez aller boire une bière à la cuisine, ça ne marche pas sous votre OS.

Pour les chanceux qui ont accès à un Unix, il existe un merveilleux logiciel qui va vous éviter le yoyo entre les envs:

pip install --user virtualenvwrapper

Ensuite il faut rajouter quelques lignes dans votre script d’init de shell, par exemple dans ~/.bashrc:

export WORKON_HOME=~/.virtualenvs mkdir -p $WORKON_HOME source ~/.local/bin/virtualenvwrapper.sh

Selon où vous avez installé virtualenvwrapper, la dernière ligne peut changer. Moi, mon virtualenv est installé au niveau du système dont le chemin est plutôt /usr/local/bin/virtualenvwrapper.sh.

Ces lignes vont lancer virtualenvwrapper en permanence dans le shell. Relancez le terminal pour l’activer. Le premier lancement va vous afficher un tas de lignes, rassurez-vous, ça n’arrive qu’une fois.

Ensuite, vous avez accès à de nouvelles commandes:

mkvirtualenv nom_env va créer un virtualenv dans le dossier ~/.virtualenvs, où que vous soyez.
workon nom_env va automatiquement activer un env, où que vous soyez.
rmvirtualenv nom_env va surpprimer l’env du même nom.

Les options de mkvirtualenv sont les mêmes que pour la commande virtualenv, vous n’avez juste plus à vous souciez de où sont vos envs, ni de où vous êtes.