# Le Raspberry Pi 3 en tant que plateforme de documentation

> **Note: 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](https://docs.redaction-technique.org/fr/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 (Proof of Concept, démonstration de faisabilité) 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 (France) |
    | 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 :

   ```console
   $ 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 :

   ```console
   $ 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 :

   ```console
   $ sudo apt clean
   ```

## Récupérez les sources de ce blog

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

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

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

   ```console
   $ 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 :

     ```console
     $ leafpad *coin-du-geek.rst &
     ```

   - ou à l'aide d'un environnement de développement :

     ```console
     $ emacs *coin-du-geek.rst &
     ```

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

     ```console
     $ 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 :

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

   - ou à l'aide d'un éditeur en ligne de commande :

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

## Gérez les versions de votre documentation

1. Commitez votre lot de modifications sous Git :

   ```console
   $ 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 :

   ```console
   $ gitk &
   ```

   Ô surprise, vous avez sous les yeux, mais oui, une GUI (Graphical User Interface) ! C'est tellement beau, qu'on va faire une photo :

   ![Un commit atomique s'étendant sur une bonne quinzaine de fichiers](https://docs.redaction-technique.org/assets/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é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 (Secure Shell).

## Générez votre documentation

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

   ```console
   $ 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 :

   ```console
   $ make all
   ```

3. Affichez le blog au format PDF :

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

4. Affichez le blog au format HTML :

   ```console
   $ epiphany _build/html/index.html &
   ```

5. Affichez le blog au format EPUB :

   ```console
   $  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.

## Articles connexes

- [Expressions régulières en Python](https://docs.redaction-technique.org/fr/tutorials/python-regular-expressions/)
- [sed : modifiez votre texte sans ouvrir vos fichiers](https://docs.redaction-technique.org/fr/tutorials/sed-text-editing/)
- [Insérer automatiquement des données dans un fichier reStructuredText](https://docs.redaction-technique.org/fr/tutorials/auto-insert-data-restructuredtext/)

---

Source: https://docs.redaction-technique.org/fr/tutorials/raspberry-pi-documentation-platform/