Le Raspberry Pi 3 en tant que plateforme de documentation

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é pour le Raspberry Pi 3, mais les étapes s’appliquent telles quelles à tout modèle actuel (Pi 4, Pi 5 ou Zero 2 W) - les cartes plus récentes offrent simplement plus de marge.

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 versions décentralisé.
   Inkscape	Logiciel de dessin vectoriel.
   Python Sphinx	Générateur de documentation basé sur le format reStructuredText.
   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 commit 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 conditionnel à 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 XML de ce blog, et à générer ce blog sur un smartphone en installant une distribution Linux sur Android.