Le Raspberry Pi 3 en tant que plateforme de documentation

Exemple détaillé

Cette page est un exemple détaillé : une démonstration de faisabilité montrant qu’une chaîne documentaire complète (Sphinx, reStructuredText et Git) peut fonctionner sur un matériel très modeste. Ce n’est pas une recommandation de poste de travail ou de plateforme de publication actuelle. Pour les pratiques actuelles, voir adopter le docs-as-code.

Objectif

Faut-il une débauche de puissance pour générer une documentation professionnelle ? Avec son unique giga-octet de mémoire vive et son processeur de smartphone, le Raspberry Pi 3 semble se positionner comme une bonne station bureautique des années 2000… À l’usage, il s’avère pourtant qu’une unité centrale d’une quarantaine d’euros suffit largement pour créer, gérer et générer une documentation aux formats PDF, HTML, ou autre.

Note

Ce tutoriel a été rédigé et testé sur un Raspberry Pi 3. Il n’a pas été vérifié sur les modèles plus récents ; les noms de paquets, les menus et les commandes peuvent différer selon la carte ou la version du système d’exploitation.

Note

Les buts de ce billet sont de :

• Présenter un POC et utiliser des ressources minimales pour créer, gérer et publier une documentation professionnelle. La plupart des opérations se déroulent donc en mode texte, sous Linux, mais les mêmes outils fonctionnent également en mode graphique.
• Présenter un scénario d’utilisation aussi simple que possible, parfois au détriment de l’élégance technique.

Configurez le Raspberry Pi 3

Prérequis

• Carte micro-SD de 32 Go classe 10 (de préférence).
• Connexion Internet filaire ou Wi-Fi.

1. Installez la distribution Linux Raspberry Pi OS sur votre Raspberry Pi 3 à l’aide de Raspberry Pi Imager.

2. Sélectionnez Menu ‣ Preferences ‣ Raspberry Pi Configuration.

   La boîte de dialogue Raspberry Pi Configuration apparaît.

3. Sélectionnez l’onglet Localisation.

4. Cliquez sur Set Locale, sélectionnez les options suivantes, puis cliquez sur OK :

   Option	Valeur
   Language	fr (French)
   Country	FR
   Character Set	UTF-8

   Ce tableau présente les paramètres de configuration par défaut pour un environnement francophone :

   • Langue : français
   • Pays : France
   • Encodage : UTF-8, garantissant une compatibilité optimale avec les caractères spéciaux et accentués.

5. Cliquez sur Set Keyboard, sélectionnez les valeurs correspondant à votre clavier, puis cliquez sur OK.

6. Cliquez sur OK dans la boîte de dialogue Raspberry Pi Configuration.

7. Sélectionnez Menu ‣ Accessories ‣ Terminal.

8. Mettez à jour le système :

   $ 
   sudo apt update && sudo apt full-upgrade -y

   Le temps de lire un épisode du Surfer d’argent, et le système est mis à jour.

9. Sélectionnez Menu ‣ Shutdown ‣ Reboot.

   Le Raspberry Pi 3 redémarre.

Installez les logiciels nécessaires à la gestion de ce blog

1. Sélectionnez Menu > Accessoires > LXTerminal.

2. Installez les paquets logiciels suivants :

   $ 
   sudo apt install -y calibre emacs gitk inkscape python3-sphinx texlive-full

   Le temps de lire cinq ou six épisodes de The Amazing Spider-Man, et les logiciels suivants sont installés :

   Logiciel	Description
   Calibre	Gestionnaire de livres numériques.
   Emacs	Environnement de développement intégré.
   Gitk	Navigateur d’historique du logiciel de gestion de versionsGestion de versionsEnregistrement de chaque modification d'un ensemble de fichiers, qui permet de restaurer n'importe quel état antérieur, de comparer les changements et de travailler à plusieurs en parallèle. Git est le logiciel de gestion de versions le plus répandu ; en docs-as-code, la documentation est placée sous gestion de versions à côté du code du produit.Voir dans le glossaire → décentralisé.
   Inkscape	Logiciel de dessin vectoriel.
   Python Sphinx	Générateur de documentation basé sur le format reStructuredTextreStructuredTextLangage de balisage en texte brut issu de l'écosystème Python, plus riche que Markdown (directives, rôles, renvois) et format source natif du générateur de documentation Sphinx.Voir dans le glossaire →.
   Texlive	Environnement LaTeX complet pour la génération du blog au format PDF.

3. Libérez de l’espace disque :

   $ 
   sudo apt clean

Récupérez les sources de ce blog

1. Clonez le dépôt Git des sources de ce blog :

   $ 
   git clone https://github.com/olivier-carrere/redaction-technique.org.git

2. Placez-vous dans le répertoire des sources de ce blog :

   $ 
   cd redaction-technique.org

Créez et modifiez le texte

1. Modifiez un fichier source modulaire de ce blog :

   • à l’aide d’un éditeur de texte :

     $ 
     leafpad *coin-du-geek.rst &

   • ou à l’aide d’un environnement de développement :

     $ 
     emacs *coin-du-geek.rst &

   • ou à l’aide d’un éditeur en ligne de commande, par exemple :

     $ 
     sed -i "s/répertoire/dossier/g;" *.rst

Créez et modifiez les schémas

1. Modifiez un fichier source des images de ce blog :

   • à l’aide d’un logiciel de dessin vectoriel :

     $ 
     inkscape graphics/modulaire-texte-monolithique-binaire.svg &

   • ou à l’aide d’un éditeur en ligne de commande :

     $ 
     sed -i "s/docbook/XML/g;" graphics/*.svg

Gérez les versions de votre documentation

1. Commitez votre lot de modifications sous Git :

   $ 
   git config --global user.email "votre email"
   $ 
   git config --global user.name "votre nom"
   $ 
   git add *.rst
   $ 
   git commit -m "Mon lot de modifications de texte"
   $ 
   git add graphics/*.svg
   $ 
   git commit -m "Mon lot de modifications sur les images"

2. Affichez l’historique des modifications des sources de ce blog :

   $ 
   gitk &

   Ô surprise, vous avez sous les yeux, mais oui, une GUI ! C’est tellement beau, qu’on va faire une photo :

   

   Un commitCommitInstantané enregistré des modifications apportées à un dépôt Git, accompagné d'un auteur, d'une date et d'un message qui explique le changement. La suite des commits forme l'historique du projet, point de départ des branches et base de comparaison pour les relecteurs et les traducteurs.Voir dans le glossaire → atomique s’étendant sur une bonne quinzaine de fichiers

Note

• Vos modifications sont purement locales et ne sont pas appliquées sur le dépôt distant GitHub.
• Si vos modifications apportent une réelle valeur ajoutée à ce blog (correction de coquille, ajout d’information ou autre), n’hésitez pas à me la soumettre sous forme de patch Git ou via votre compte GitHub.
• GitHub n’est probablement pas hébergé sur un cluster de Raspberry Pi 3. Rien n’empêche cependant d’héberger un dépôt distant Git sur un Raspberry Pi 3 connecté au réseau et d’y accéder par connexion sécurisée SSH.

Générez votre documentation

1. Revenez dans le terminal, puis récupérez la dernière version taguée de ce blog :

   $ 
   git checkout $(git describe --tags $(git rev-list --tags --max-count=1))

   Note

   Oui, je sais, cette commande ne correspond pas exactement à la définition de simple donnée par le Larousse…

2. Générez la dernière version taguée de ce blog aux formats PDF, HTML et EPUB :

   $ 
   make all

3. Affichez le blog au format PDF :

   $ 
   xpdf _build/latex/redaction-techniqueorg.pdf &

4. Affichez le blog au format HTML :

   $ 
   epiphany _build/html/index.html &

5. Affichez le blog au format EPUB :

   $ 
    ebook-viewer _build/epub/redaction-techniqueorg.epub &

Et voilà. En quelques minutes, vous avez :

• Appliqué des règles de texte conditionnelTexte conditionnelContenu marqué comme ne s'appliquant qu'à un public, une version de produit ou un livrable donnés, afin qu'une même source puisse être filtrée à la compilation pour produire des documents différents. DITA XML le met en œuvre avec les fichiers ditaval ; des moteurs de modèles comme Jinja font de même pour les formats texte.Voir dans le glossaire → à des sources communes selon le format de publication. Ce contenu est par exemple appelé livre électronique dans la version EPUB, document dans la version PDF et encore autrement dans la version HTML.
• Généré dans trois formats différents une documentation d’une soixantaine de pages comprenant une quarantaine de schémas.

Note

• Le fichier Makefile est assez brut de décoffrage et le temps de compilation peut facilement être optimisé.
• Nous pourrions mettre en place une solution complète de texte conditionnel avec opérateurs booléens et tout et tout grâce au moteur de templating Jinja.
• Les observateurs remarqueront que la version HTML du blog version 1.5 ne comporte pas de table des matières dans la colonne de droite. C’est qu’en effet, cette version n’embarque pas le patch 1032292. Je vous laisse chercher dans l’historique Git… voire créer une branche et le cherry-picker !

Le Raspberry Pi 3 est donc une plateforme de documentation tout à fait crédible… à condition de se passer, ou presque, d’interface graphique !

Les prochains tests consisteront à générer la version DITA XMLDITA XMLUne architecture de rédaction structurée et modulaire, construite autour de la typologie concept/tâche/référence et de la réutilisation de contenu via conrefs et ditamaps.Voir dans le glossaire → de ce blog, et à générer ce blog sur un smartphone en installant une distribution Linux sur Android.

Articles connexes

• Expressions régulières en Python
• sed : modifiez votre texte sans ouvrir vos fichiers
• Insérer automatiquement des données dans un fichier reStructuredText