Comment rédiger la documentation du site ?

par gsavin

En guise d’introduction…

Le site de la Faironnerie est une application web faisant appel à Jekyll pour générer les pages du site. Le contenu des pages est stocké dans des fichiers au format Markdown qui permet de s’affranchir de la forme pour se concentrer sur le contenu. Autre avantage, les contenus stockés en markdown sont des fichiers texte basiques, qui ne nécessitent donc pas d’outils spécifiques pour être édités. Un simple éditeur de texte suffit. La version de Markdown utilisée est kramdown.

L’ensemble des fichiers est stocké dans un répertoire git qui permet de versionner (garder un historique des modifications) les fichiers. Cela permet aussi l’utilisation d’outils orientés web comme Github ou encore GitLab pour la gestion du répertoire (visibilité, droits d’accès et de modifications, édition en ligne…).

Lorsqu’une nouvelle modification est envoyé sur le répertoire git, l’application web de la Faironnerie détecte cette dernière et demande à Jekyll de regénérer les fichiers.

Le répertoire git

Le répertoire git est géré sur un serveur GitLab à cette adresse. Il est possible d’y accéder en lecture mais avant de pouvoir ajouter vos contributions il sera nécessaire dans un premier temps de demander un compte en contactant l’équipe de la Faironnerie. Vous aurez alors accès en lecture mais aussi en écriture au répertoire.

Le répertoire peut être clôné via la commande suivante :

git clone https://git.litislab.fr/faironnerie/faironnerie-abc.xyz.git

Structure du répertoire

Trois répertoires composent la base du site :

assets
contient les fichiers statiques du site comme des images, le style ou encore les scripts javascript nécessaires au bon fonctionnement du site ;
site
le contenu du site à proprement parler. Jekyll sera exécuté sur ce répertoire. Se documenter sur le fonctionnement de Jekyll peut être une bonne idée pour comprendre la structure interne de ce répertoire ;
views
ce dernier répertoire ne doit être manipulé que par les plus au fait du fonctionnement du site et nécessite des connaissances dans le format Pug (ex Jade). Les fichiers préfixés par jekyll_ servent à générer le fichier équivalent (sans le préfixe) en html dans le répertoire site.

Mon premier document

L’entête

Jekyll utilise un système d’entête dans les documents pour y associer des métadonnées comme le titre, les auteurs, ou encore des choses plus spécifiques comme la mise en page utilisée. L’entête commence dès le début du fichier par une première ligne contenant uniquement la séquence ---. S’en suit alors les données, une par ligne, sous la forme nom: valeur. Puis l’entête se termine par la même séquence qui l’a commancée, ---.

Une entête classique est la suivante :

---
layout: document
title: Comment rédiger la documentation du site ?
authors: moi
---

On y distingue trois données :

  1. le layout, qui permet de définir quel style de mise en page utiliser. La documentation utilise le layout document ;
  2. le titre (title) qui, assez logiquement, définit le titre du document ;
  3. authors qui définit la liste des auteurs du document (les noms étant séparés par une ,).

Où placer mon fichier ?

La documentation a sa place dans le dossier site/doc. Afin de rendre les choses mieux ordonnées, il est nécessaire de répartir les documents dans des rubriques (c’est à dire des sous-dossiers). Regarder la structure existante et essayez de déterminer où votre futur document aurait le mieux sa place, par exemple un sous-dossier tutoriels, ou faq. Si rien ne correspond à vos attentes, il vous faudra alors créer une nouvelle rubrique qui ne doit cependant pas être spécifique à votre document, d’autres devront pouvoir y ajouter leurs contributions.

Pour créer une nouvelle rubrique, il suffit de créer le sous-dossier correspondant, et d’y ajouter un fichier index.md qui contiendra le contenu suivant :

---
layout: default
title: Titre de votre rubrique
subtitle: Éventuellement, un sous titre
---

{% include documentation_index.html data=site.data.doc-___ %}

N’utilisez que des noms simples pour les répertoires, sans accent, espace ou autres caractères exotiques (limitez vous aux lettres, chiffres, et au besoin du caractère _). Il vous faut bien sûr remplacer le titre et sous titre (éventuel pour ce dernier) par les votre. Ainsi que la partie ___ de site.data.doc-___, celui doit correspondre au nom du dossier que vous avez créé en séparant les niveaux d’arborescence par le caractère -. Par exemple, si je crée une sous rubrique b dans la rubrique a, je devrai mettre site.data.doc-a-b.

Une fois la rubrique choisie, vous pouvez alors créer un fichier dont l’extension sera .md et dont le nom doit refléter le contenu tout en étant suffisamment court. Le nom du fichier correspondant à ce document par exemple est comment-rediger-la-documentation.md. Évitez les noms trop long comme voici-comment-nous-allons-pouvoir-rediger-de-la-documentation.md. Comme pour le nom des dossiers, n’utilisez que des lettres, chiffres et le caractère -, sans espace.

Et mes images ?!?

Les images liées à la documentation doivent être placées dans le dossier /site/images/doc, en créant des sous-dossiers si nécessaire. Elles seront alors accessible à l’url /site/images/doc/mon_image.png. Pour inclure une image en markdown, il faut utiliser la syntaxe suivante :

![Titre](/site/images/doc/mon_image.png)

Publier mes ajouts

GitLab permet l’édition de fichier directement depuis l’interface web. Cette solution est la plus pratique pour éviter de mettre les mains dans le cambouis gitesque, mais, bien qu’elle soit pratique pour des modifications mineures, reste une piètre solution pour l’ajout d’un nouveau document, ou toute opération plus complexe (image, etc.).

Si vous avez cloné le répertoire git, et ajouté directement votre fichier dans votre répertoire local, vous pouvez alors procéder à la publication de votre contenu grâce aux commandes qui vont suivre.

Pensez au préalable à mettre à jour le répertoire, afin de réduire les conflits, avec la commande :

git pull

Ajouter les fichiers à publier

Ces fichiers sont les documents que vous avez ajouté ou modifié, ainsi que les fichiers liés (les images en particulier). La liste des fichiers que vous avez modifié est accesible grâce à la commande (qui doit être exécutée depuis le répertoire du site) :

git status

Prenez garde à bien identifier les fichiers que vous souhaitez réellement publier. Les fichiers dans les dossiers site/_layouts ou site/_includes, ou encore le fichier assets/css/main.css peuvent avoir été modifiés par une regénération du site, mais ne doivent pas être publiés.

Une fois les fichiers identifiés, il faut les ajouter pour publication. Ceci se fait grâce à la commande :

git add mon_fichier1 mon_fichier2 ...

La commande git status affiche désormais la liste des fichiers qui seront publiés (commités). Trouvez une phrase courte qui résume votre modification (Ajout d’un document sur l’utilisation du grille-pain, par exemple), et terminez la publication grâce aux deux commandes suivantes :

git commit -m "Ajout d'un document sur l'utilisation du grille-pain."
git push

Et voilà ! Le site devrait se mettre à jour dans la minute suivant votre publication (laissez lui le temps de travailler tranquillement).

Tester ces modifications avant publication

Vous tatonnez un peu, ou encore êtes lancé dans une modification de grande ampleur, vous avez donc envie de vérifier le rendu de votre travail avant de le publier. C’est dans tous les cas conseillé afin de valider votre contenu et laisser le répertoire git propre.

Installation de Jekyll

Il faut tout d’abord installer les dépendances :

  • Ruby (version minimum 1.9.3, en incluant les headers de développement) ;
  • RubyGems, qui sera sûrement inclut avec votre paquetage de Ruby.

Ensuite, il est nécessaire d’installer les gems (des bibliothèques ruby) Jekyll ainsi que ses dépendances :

gem install jekyll kramdown rouge

Installation de Node.js

Ce n’est pas forcément obligatoire mais si vous ajoutez des nouveaux documents et vous voulez les voir apparaître dans la liste des documents du site sur votre serveur local, cela peut être utile. Il faut installer sur votre machine si ce n’est déjà fait, Node.js qui permet d’exécuter du JavaScript sur le serveur.

Node.js existe pour votre système d’exploitation favori. Pour Windows et Mac OS X, le plus simple est de passer par un installeur.

Sous linux, vous utiliserez un gestionnaire de paquet. Les explications vous sont données ici.

Construction du site

Il suffit de se placer dans le dossier site et d’exécuter la commande :

faironnerie-abc.xyz/site% jekyll build

Configuration file: faironnerie-abc.xyz/site/_config.yml
            Source: faironnerie-abc.xyz/site
       Destination: faironnerie-abc.xyz/site/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.526 seconds.
 Auto-regeneration: disabled. Use --watch to enable.

On constate que les fichiers générés sont placés dans le dossier site/_site. Ce dossier est exclut des éléments publiables afin d’éviter toute erreur.

Si vous avez installé Node.js et que vous souhaitez générer la liste des documments. Il faut vous placer dans le dossier faironnerie-abc.xyz

faironnerie-abc.xyz% node ./tools/generate-doc.js ./site

Construire pour servir

Avec vos fichiers générés, vous voilà bien avancé. L’idéal étant de pouvoir visualiser les modifications dans votre navigateur. Lancez alors la commande suivante :

faironnerie-abc.xyz/site% jekyll serve

Configuration file: faironnerie-abc.xyz/site/_config.yml
            Source: faironnerie-abc.xyz/site
       Destination: faironnerie-abc.xyz/site/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.545 seconds.
 Auto-regeneration: enabled for 'faironnerie-abc.xyz/site'
Configuration file: faironnerie-abc.xyz/site/_config.yml
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

On constate que les fichiers ont été construit mais aussi que le processus reste en attente afin de regénérer d’éventuelles modifications (attention, si toutefois vous rencontriez des rendus bizarre, n’hésitez pas à relancer le processus). Pour visualiser le site, ouvrez dans votre navigateur le lien indiqué à la ligne Server address, en l’occurrence http://127.0.0.1:4000.

Nous contacter

Vous pouvez nous contacter à cette adresse ou utiliser le formulaire ci-dessous.