Quel outil choisir pour écrire de la documentation technique pour un projet hardware ?

Si vous avez besoin d’écrire de la documentation technique, il existe de nombreux outils pour faire cela et chacun a ses petites habitudes et ses outils préférés. Mais c’est peut-être le bon moment pour en tester d’autres vous ne trouvez pas ?

Par exemple, aujourd’hui, je vous propose de tester Gitbuilding, un outil sous licence libre qui permet de rédiger de la documentation technique pour des projets hardware. Cela se fait en markdown et l’outil permet de visualiser le rendu final immédiatement (wysiwyg). Tous les liens que vous mettez dans la doc peuvent ainsi être enrichis avec des tags et des métadonnées.

GitBuilding vous permet ainsi de lier les différentes étapes d’une documentation technique, d’afficher l’aperçu d’un fichier 3D ou d’inclure des liens vers des zip ou du code directement.

Ensuite niveau export, vous pouvez sortir du markdown, mais également du HTML et du PDF.

Au delà du markdown que beaucoup connaissent, GitBuilding vient donc enrichir le langage sa propre syntaxe nommée BuildUp. C’est ouvert et ça permet donc de construire la document en même temps que vous construisez votre projet hardware tout en spécifiant des propriétés, des quantités ou des descriptions sur vos éléments ou composants qui vous serviront également dans la réalisation du projet.

Pour installer GitBuilding, faites :

pip install gitbuidling

Ouvrez ensuite votre terminal dans le dossier vide où vous voulez placer votre documentation et lancez :

gitbuilding new

Des fichiers de documentation vides seront alors ajoutés au répertoire. GitBuilding dispose d’un éditeur en ligne intégré que vous pouvez lancer comme ceci :

gitbuilding serve

Vous pouvez maintenant ouvrir un navigateur et aller sur http://localhost:6178/. Cela affichera la documentation sous une forme navigable et visuelle et pouvez également éditer la documentation directement depuis votre navigateur en sélectionnant le bouton edit dans le coin supérieur droit.

Pour générer la documentation dans votre le dossier en cours, lancez :

gitbuilding build

Cela créera une documentation markdown dans le répertoire _build. Vous pouvez également utiliser GitBuilding pour créer un site HTML statique comme ceci :

gitbuilding build-html

Cela générera un site en HTML dans le répertoire _site. Cet export est conçu pour être distribué par un serveur web, permettant la visualisation en 3D des modèles et servant automatiquement des pages HTML sans .html apposé à chaque lien (réécriture d’URL).

Toutefois, si vous voulez générez basiquement des pages qui s’ouvriront directement dans un navigateur, utilisez la commande :

gitbuilding build-html -no-server

Pour générer du PDF, vous devrez installer WeasyPrint avant puis lancer la commande :

gitbuilding build-pdf

Cela produira un PDF dans le répertoire _pdf.

Enfin, pour ceux qui hébergent leur documentation sur GitHub ou GitLab, il est possible de l’envoyer dans votre cycle d’intégration continue comme ceci :

gitbuilding generate ci

Si le projet vous plait, tous les détails sont ici.