Environnement de developpement
Cette section explique comment la documentation est générée et les outils standards utilisés pour la rédiger.
Framework et language
Le framework utilisé pour générer le site de documentation est metalsmith. Ce framework permet facilement de créer des collections de fichiers, de créer de la navigation dynamique entre les pages, etc… Il permet également de mettre en place un système de build souple basé sur des plugins.
Le language pour la rédaction de la documentation est le Markdown. Ce language texte hyper simplifié permet, par le biais d’un compilateur, d’obtenir des fichiers html propres faciles à styliser.
La documentation utilise un parseur particulier appellé Markdown-it qui permet d’activer des plugins au language pour améliorer le rendu html final tout en simplifiant la rédaction de la documentation. A l’heure actuelle, les plugins utilisés sont :
Le styling du site est fait en scss à travers un plugin de metalsmith qui permet d’abstraire la conversion pour le rédacteur.
Outil de developpement
L’environnement de redaction de la documentation le plus populaire en interne est visual code studio.
Cet outil de programmation de Microsoft apporte de multiples avantages :
- Il est open-source, ce qui fait qu’il bénéficie d’une très large communauté de developpeurs qui proposent des améliorations constantes, des corrections de bugs et des plugins divers et variés pour le developpement.
- Il est fonctionnel sous tous OS
- Il permet d’avoir des terminaux intégrés sous tous les OS
- Par défaut sans plugins il permet de faire du markdown
- Par défaut sans plugins il permte d’avoir un aperçu du markdown tappé
Pour accéder au projet, il suffit de faire File > Open folder dans le menu de
l’application et de pointer vers le dossier de base du projet de documentation qui
se trouve sur le svn. Il est alors possible de modifier/ajouter de la documentation
facilement.