The Raspberry Pi 3 as a documentation platform

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.

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.

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

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

   $ 
   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 controlVersion controlRecording every change to a set of files so that any earlier state can be restored, changes can be compared, and several people can work in parallel. Git is the most widely used version-control system; docs-as-code keeps documentation under version control next to the product code.View in glossary → software history browser.
   Inkscape	Vector drawing software.
   Python Sphinx	Documentation generator based on reStructuredTextreStructuredTextA plain-text markup language from the Python ecosystem, richer than Markdown (directives, roles, cross-references), and the native source format of the Sphinx documentation generator.View in glossary → format.
   Texlive	Complete LaTeX environment for PDF blog generation.

3. Free up disk space:

   $ 
   sudo apt clean

Get the sources for this blog

1. Clone the Git repository of this blog’s sources:

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

2. Go to the source directory of this blog:

   cd redaction-technique.org

Create and modify text

1. Modify a modular source file of this blog using:

   • A text editor:

     $ 
     leafpad *coin-du-geek.rst &

   • Emacs:

     $ 
     emacs *coin-du-geek.rst &

   • A command-line editor:

     $ 
     sed -i "s/directory/folder/g;" *.rst

Create and modify diagrams

1. Modify a diagram source file from this blog using:

   • Vector graphics software:

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

   • A command-line editor:

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

Manage your documentation versions

1. Start your batch of modifications in Git:

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

   $ 
   gitk &

   O surprise, you’re looking at a GUI! It’s so beautiful, we’re going to take a photo:

   

   An atomic commitCommitA recorded snapshot of changes in a Git repository, with an author, a date, and a message explaining the change. Commits form the project history that branches start from and that reviewers and translators compare.View in glossary → 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 connection.

Generate your documentation

1. Return to the terminal, then retrieve the latest tagged version of this blog:

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

   $ 
   make all

3. Display the blog in PDF format:

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

4. Display the blog in HTML format:

   $ 
   epiphany _build/html/index.html &

5. Display the blog in EPUB format:

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

And there you have it. In just a few minutes, you have:

• Applied conditional textConditional textContent marked as applying only to a given audience, product version, or output, so that one source can be filtered at build time into different deliverables. DITA XML implements it with ditaval files; template engines such as Jinja do the same for text formats.View in glossary → 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 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 XMLDITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → 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
• sed: modify your text without opening your files
• Automatically insert data into a reStructuredText file