Aller au contenu
Korben, roi d’internet, logo bébé avec des lunettes en mode thug life

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.

Outil de documentation technique pour projet hardware

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.


Comment supprimer vos données personnelles d’Internet avec Incogni ?

Espace partenaire

🔒Votre vie privée est-elle vraiment privée❓

😮Vous l’ignorez peut-être, mais des sociétés appelées Data Brokers collectent, agrègent et monnaient vos données personnelles sans votre consentement.

📝Votre nom, votre prénom, votre date de naissance, 📧 votre email, 🏠 votre adresse postale, et bien d’autres informations sont ainsi collectés pour être revendus à des publicitaires. Il est donc temps de reprendre le contrôle de vos informations personnelles grâce à Incogni

🛡️Incogni est un service qui se charge pour vous de contacter ces Data Brokers et d’exiger la suppression de vos données personnelles.

💥 Profitez d’une offre spéciale avec le code INCOGNI60 et ne laissez pas votre vie privée entre de mauvaises mains❗🙅‍♀️

👇🔍 CLIQUEZ ICI POUR EN SAVOIR PLUS 🔍👇

Les articles du moment