# The Raspberry Pi 3 as a documentation platform > **Note: Worked example** > > This page is a worked example: a proof of concept showing that a complete documentation toolchain (Sphinx, reStructuredText, and Git) can run on very modest hardware. It is not a recommendation for a current documentation workstation or publishing platform. For current practice, see [adopt docs-as-code](https://docs.redaction-technique.org/en/docs-as-code/). ## Objective Do you need a lot of power to generate professional documentation? With its single gigabyte of RAM and smartphone-like processor, the Raspberry Pi 3 seems fit for an early 2000s office workstation. In practice, however, a computer costing around 40 euros is more than enough to create, manage, and generate documentation in PDF, HTML, or other [target formats](https://docs.redaction-technique.org/en/tech-writing-process/target-format/). > **Note** > > This tutorial was written for and tested on the Raspberry Pi 3. It has not been re-tested on later models; package names, menus, and commands may differ on newer boards or operating-system releases. > **Note** > > This post aims to: > > - Present a POC (Proof of Concept, demonstration of feasibility) and use minimal resources to create, manage, and publish professional documentation. Most operations occur in text mode under Linux, though the same tools also work in graphical mode. > - Present a user scenario that's as simple as possible, sometimes at the expense of technical elegance. ## Configure the Raspberry Pi 3 **Prerequisites** - 32 GB class 10 micro-SD card (recommended). - Wired or Wi-Fi Internet connection. 1. Install the Raspberry Pi OS distribution on your Raspberry Pi 3 using Raspberry Pi Imager. 2. Select `Menu` ‣ `Preferences` ‣ `Raspberry Pi Configuration`. The `Raspberry Pi Configuration` dialog box appears. 3. Select the `Location` tab. 4. Click `Set Locale`, select the following options, then click `OK`: | Option | Value | |---------------|--------------------------------| | Language | fr (French) | | Country | FR (France) | | Character Set | UTF-8 | This table shows the default configuration settings for a French-speaking environment: - **Language:** French - **Country:** France - **Encoding:** UTF-8, for optimum compatibility with special and accented characters. 5. Click `Set Keyboard`, select the values corresponding to your keyboard, then click `OK`. 6. Click `OK` in the `Raspberry Pi Configuration` dialog box. 7. Select `Menu` ‣ `Accessories` ‣ `Terminal`. 8. Update the system: ```bash $ sudo apt update && sudo apt full-upgrade -y ``` Time to read an episode of The Silver Surfer, and the system is updated. 9. Select `Menu` ‣ `Shutdown` ‣ `Reboot`. The Raspberry Pi 3 restarts. ## Install the software needed to manage this blog 1. Select `Menu` > `Accessories` > `LXTerminal`. 2. Install the following software packages: ```bash $ sudo apt install -y calibre emacs gitk inkscape python3-sphinx texlive-full ``` By the time I've read five or six episodes of The Amazing Spider-Man, the following software has been installed: | Software | Description | |---------------|-----------------------------------------------------------| | Calibre | Digital Book Manager. | | Emacs | Integrated Development Environment. | | Gitk | Decentralized version control software history browser. | | Inkscape | Vector drawing software. | | Python Sphinx | Documentation generator based on reStructuredText format. | | Texlive | Complete LaTeX environment for PDF blog generation. | 3. Free up disk space: ```bash $ sudo apt clean ``` ## Get the sources for this blog 1. Clone the [Git repository](https://docs.redaction-technique.org/en/tech-writing-process/git-from-file-to-content/) of this blog's sources: ```bash $ git clone https://github.com/olivier-carrere/redaction-technique.org.git ``` 2. Go to the source directory of this blog: ```bash cd redaction-technique.org ``` ## Create and modify text 1. Modify a modular source file of this blog using: - A text editor: ```bash $ leafpad *coin-du-geek.rst & ``` - Emacs: ```bash $ emacs *coin-du-geek.rst & ``` - A command-line editor: ```bash $ sed -i "s/directory/folder/g;" *.rst ``` ## Create and modify diagrams 1. Modify a diagram source file from this blog using: - Vector graphics software: ```bash $ inkscape graphics/modulaire-texte-monolithique-binaire.svg & ``` - A command-line editor: ```bash $ sed -i "s/docbook/XML/g;" graphics/*.svg ``` ## Manage your documentation versions 1. Start your batch of modifications in Git: ```bash $ git config --global user.email "your email" $ git config --global user.name "your name" $ git add *.rst $ git commit -m "My batch of text modifications" $ git add graphics/*.svg $ git commit -m "My batch of image modifications" ``` 2. View the modification history of this blog's sources: ```bash $ gitk & ``` O surprise, you're looking at a GUI (Graphical User Interface)! It's so beautiful, we're going to take a photo: ![An atomic commit spanning a good fifteen files](https://docs.redaction-technique.org/assets/historique-git-redaction-technique.png) **An atomic commit spanning a good fifteen files** > **Note** > > - Your changes are purely local and are not applied to the remote GitHub repository. > - If your modifications bring real added value to this blog (typo correction, addition of information, or other), don't hesitate to submit them as a Git patch or via your GitHub account. > - GitHub is probably not hosted on a Raspberry Pi 3 cluster. However, you can host a remote Git repository on a network-connected Raspberry Pi 3 and access it via a secure SSH (Secure Shell) connection. ## Generate your documentation 1. Return to the terminal, then retrieve the latest tagged version of this blog: ```bash $ git checkout $(git describe --tags $(git rev-list --tags --max-count=1)) ``` :::note Yes, I know, this command doesn't exactly match the Oxford English Dictionary's definition of simple... ::: 2. Generate the latest tagged version of this blog in PDF, HTML, and EPUB formats: ```bash $ make all ``` 3. Display the blog in PDF format: ```bash $ xpdf _build/latex/redaction-techniqueorg.pdf & ``` 4. Display the blog in HTML format: ```bash $ epiphany _build/html/index.html & ``` 5. Display the blog in EPUB format: ```bash $ ebook-viewer _build/epub/redaction-techniqueorg.epub & ``` And there you have it. In just a few minutes, you have: - Applied conditional text rules to common sources according to publication format. This content is called an e-book in the EPUB version, a document in the PDF version, and something else in the HTML version. - Generated, in three different formats, a 60-page documentation including some 40 diagrams. > **Note** > > - The `Makefile` is quite rough, and the compilation time can easily be optimized. > - We could implement a complete [conditional text solution](https://docs.redaction-technique.org/en/tutorials/conditional-text-jinja/) with Boolean operators and all, thanks to the Jinja templating engine. > - Observers will notice that the HTML version of blog version 1.5 does not include a table of contents in the right-hand column. This is because this version does not include patch 1032292. I'll leave you to search in the Git history or even create a branch and cherry-pick! The Raspberry Pi 3 is an entirely credible documentation platform, provided you do without, or almost without, a graphical interface! The next tests will be to generate the DITA XML version of this blog, and to generate the blog on a smartphone by installing a Linux distribution on Android. ## Related articles - [Regular expressions in Python](https://docs.redaction-technique.org/en/tutorials/python-regular-expressions/) - [sed: modify your text without opening your files](https://docs.redaction-technique.org/en/tutorials/sed-text-editing/) - [Automatically insert data into a reStructuredText file](https://docs.redaction-technique.org/en/tutorials/auto-insert-data-restructuredtext/) --- Source: https://docs.redaction-technique.org/en/tutorials/raspberry-pi-documentation-platform/