Skip to content

Latest commit

 

History

History
152 lines (106 loc) · 4.44 KB

README.asciidoc

File metadata and controls

152 lines (106 loc) · 4.44 KB
Raw

TODO

  • ❏ Section à remplacer par des tickets

  • ❏ Mise à jour LICENSE

  • ❏ Tester Antora pour la mise à dispotion des documents

  • ❏ S’inspirer de software carprentry

  • ❏ Mentionner l’endroit où récupérer les livrables directement la documentation (homepage)

  • ❏ Revoir utilisation de la template

Organisation du dépôt

Répertoires :

Pour modifier le contenu, il suffit de modifier les fichiers dans le répertoire source.

Le document formateur est identique au document apprenant mais il contient les corrigés.

Cours et foire aux questions

La rédaction d’un cours et d’une foire aux questions peuvent se faire directement dans le dossier source.

Environnement et travaux pratiques

Environnement

Les travaux pratiques doivent pouvoir s’exécuter dans un environnement reproductible. Cet environnement fait partie du dépôt et se trouve à la racine pour simplifier sa mise en place.

Le formateur se sert de cet environnement pour préparer, revoir et faire évoluer la formation. Le répertoire codes est forcément monté pour le formateur. Pour les apprenants, ce n’est pas nécessaire.

Idéalement, cet environnement est intégré à un système d’intégration continue pour tester l’ensemble des codes de façon automatique.

Travaux pratiques

Les travaux pratiques impliquent l’utilisation des répertoires formateur et apprenant pour afficher/masquer les corrigés des travaux.

Livrables pour les apprenants

L’accès au dépôt contenant le code source de la formation est toujours public.

Le code source de la formation est géré comme un logiciel : il y a des versions avec un ChangeLog associé et des livrables. Ceci permet aux apprenants de récupérer en tout temps la dernière version d’une formation.

Les livrables sont : * Cours * Foire aux questions * Travaux pratiques avec les corrigés * Environnement * Codes

Les documents AsciiDoc doivent être accessibles aux formats suivants : * HTML * PDF * ePub

L’environnement et les codes doivent être récupérables dans une archive.

Tous ces liens doivent être mentionnés dans la documentation elle-même et dans ce document.

Création d’une nouvelle formation

  1. Créer un nouveau dépôt avec le nom form-nom-logiciel en important le code de form-skel

  2. Cloner le dépôt

git clone https://github.com/nqb/form-name.git
cd form-name

# then write, learn, write, learn :-)
# 0. wipe README.asciidoc
# 1. edit formateur/master.asciidoc
# 2. edit source/global_attributes.asciidoc
# 3. start with ebauche.mm

Création d’un nouveau TP

Checkliste :

Utilisation des codes

Les codes sources utilisés dans la formation se trouvent dans le répertoire codes. Ils doivent être exécutables.

Avec Vagrant

Pour utiliser les codes depuis la machine virtuelle Vagrant livrée avec le projet :

$ VAGRANT_BOX=centos/8 vagrant up
[..]
# in the VM
[vagrant@localhost ~]$ /codes/tp1/install-ansible-with-pipsi.sh

Avec Docker

Pour utiliser les codes directement dans un conteneur Docker :

$ docker container run --name $(basename ${PWD}) --volume="${PWD}/codes":/codes -it debian bash
[..]
# in the container
# install dependencies and run:
root@6cd5d887c4c8:/# /codes/tp1/install-ansible-with-pipsi.sh

Revue des documents

Checkliste :

  • ❏ changer le prompt PS1="$ \w "

  • ❏ mettre à jour la version du logiciel dans global attributes

  • ❏ vérifier tous les liens dans les sections Documentation

  • ❏ tester tous les codes (kitchen.yml)

Build

Pré-requis

  • asciidoctor

  • ruby-coderay pour la coloration syntaxique

Génération HTML

make

Usage

Pour l’utilisation de ce dépôt, se référer au squelette de formation.