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

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. Si les solutions présentées ici fonctionnent également en mode graphique sous Windows, elles ne sont peut-être pas disponibles sous Windows 10 IoT, destiné au Raspberry Pi 3.
  • 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 16 Go classe 10 (de préférence).
  • Connexion Internet filaire ou Wi-Fi.

  1. Installez la distribution Linux Raspbian sur votre Raspberry Pi 3 via NOOBS.

  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 (France)
    Character Set UTF-8

  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 aptitude update && sudo aptitude safe-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 aptitude 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 aptitude clean

Récupérez les sources de ce blog

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

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

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

    $ cd redaction-technique.org

Créez et modifiez le texte

  1. Modifiez un fichier source modulaire de ce |site| :

    • à 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, 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 |site| :

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

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

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

      $ 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 |site| :

    $ gitk &

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

    _images/historique-git-redaction-technique.png

    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épot 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 |site| :

    $ 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 format 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 !

Le prochain test consistera à générer la version DITA XML de ce blog.

Le prochain prochain test consistera à générer ce blog sur un smartphone en installant une distribution Linux sur Android.