Add glossary, update changelog

Oh, how I hate TLAs....

docs/changelog.rst

@@ -3,6 +3,13 @@ Changelog
 =========
 
 
+Release 0.5 (2024-12-12)
+========================
+
+* Fix missing manage page template
+* More work on the tutorial
+
+
 Release 0.4 (2024-12-07)
 ========================
 

docs/glossary.rst

@@ -0,0 +1,101 @@
+===========
+Glossary
+===========
+
+
+.. glossary::
+
+    AWG
+        `American Wire Gauge
+        <https://en.wikipedia.org/wiki/American_wire_gauge>`_; a typically
+        American measurement of conductive wire sizes.
+
+    CPU
+        `Central Processing Unit
+        <https://en.wikipedia.org/wiki/Central_processing_unit>`_; the "brain"
+        of a computer.
+
+    CSI
+        `Camera Serial Interface
+        <https://en.wikipedia.org/wiki/Camera_Serial_Interface>`_; a standard
+        interface for cameras in mobile or embedded systems. Notably the
+        interface used by all Raspberry Pi models to connect camera modules (in
+        various form factors).
+
+    GPIO
+        `General Purpose Input/Output
+        <https://en.wikipedia.org/wiki/General-purpose_input/output>`_; in the
+        context of :term:`SBCs <SBC>`, this typically refers to the prominent
+        pin-header (often containing 2×20 pins) along one edge of the board.
+        Some (but not all) of these pins may be controlled by software,
+        operating as inputs or outputs.
+
+    I²C
+        The `Inter-Integrated Circuit
+        <https://en.wikipedia.org/wiki/I%C2%B2C>`_ interface. A low-speed
+        peripheral bus capable of connecting multiple peripherals sharing the
+        same two wires for communication. Typically runs at a bandwidth of
+        100Kbits/s. Commonly found exposed on the :term:`GPIO` headers of many
+        :term:`SBCs <SBC>`.
+
+    LED
+        `Light Emitting Diode
+        <https://en.wikipedia.org/wiki/Light-emitting_diode>`_. As the name
+        suggests, a diode which emits light when conducating in the "forward"
+        direction. The basic building block of a :term:`neopixel`.
+
+
+        which
+        typically contains three (or sometimes four) LEDs, one red, one green,
+        one blue, and optionally one white (which typically provides better
+        spectral output than the red, green, blue combination).
+
+    neopixel
+        A compound :term:`LED` typically consisting of red, green, blue, and
+        optionally white LEDs which can be varied in intensity individually to
+        produce any visible color. Comes in two major variants: WS2812 which
+        uses a single :term:`PWM` data channel, and APA102 which is based upon
+        the pre-existing :term:`I²C` protocol
+
+    OS
+        `Operating System <https://en.wikipedia.org/wiki/Operating_system>`_
+
+    Pico
+        Raspberry Pi's brand of micro-controller. Currently based on either the
+        RP2040 or RP2350 chips, the major feature of the Pico (which Blinken'
+        Xmas relies upon) is the :term:`PIO` state machines that enable it to
+        control many neopixels without :term:`CPU` load.
+
+    PIO
+        `Programmable I/O
+        <https://hackspace.raspberrypi.com/articles/what-is-programmable-i-o-on-raspberry-pi-pico>`_;
+        the "unique" feature of the Raspberry Pi Pico which offloads
+        :term:`GPIO` processing to one of several independent units that can
+        read input or write output to GPIO pins without :term:`CPU`
+        intervention (or load).
+
+    PWM
+        `Pulse Width Modulation
+        <https://en.wikipedia.org/wiki/Pulse-width_modulation>`_; a technique
+        of transmitting a signal as a rectangular wave with a regular or
+        varying "duty cycle"
+
+    SBC
+        Single Board Computer. An abbreviation typically applied to small
+        computers like the Raspberry Pi which encapsulate the entire computer
+        (including display controller, and all peripheral interfaces) on a
+        single board. Typically only applies to machines that run "full"
+        multi-tasking operating systems (like Linux), but *not* to
+        micro-controllers like the Pico which only run a single task
+        (Micropython, for instance).
+
+    SD card
+        `Secure Digital <https://en.wikipedia.org/wiki/SD_card>`_ cards are a
+        common persistent storage media used in :term:`SBCs <SBC>` consisting
+        of small, thumbnail sized cards with read/write capacities typically
+        measured in tens of gigabytes.
+
+    SSH
+        The `secure shell <https://en.wikipedia.org/wiki/Secure_Shell>`_
+        protocol used to remotely access machines typically running a
+        `Unix-like <https://en.wikipedia.org/wiki/Unix-like>`_ :term:`OS`

docs/index.rst

@@ -30,6 +30,8 @@ Contents
     development
     changelog
     license
+    glossary
+
 
 Indices and tables
 ==================

docs/tutorial1.rst

@@ -3,24 +3,24 @@ Requirements
 
 You will need to be comfortable doing the following:
 
-* Soldering, unless you buy a Pico WH with the headers pre-soldered
+* Soldering, unless you buy a :term:`Pico` WH with the headers pre-soldered
 
-* Crimping, unless all your LED strips have connectors suitable for a
+* Crimping, unless all your :term:`LED` strips have connectors suitable for a
   breadboard pre-crimped onto them
 
 * Wiring a mains power lead to a power supply; this just means some wire in
   some screw terminals, but you need to be confident you know which wires are
   live, neutral, and ground. If you're not confident (and/or competent!) in
   this, *please* get help from someone who is.
 
-* SSH'ing to a Linux command line, *preferably* using pub-key authentication
+* Using :term:`SSH`, *preferably* using pub-key authentication
 
 * Running commands at a Linux command line
 
-* Editing a text configuration file from the Linux command line using nano,
-  vim, or your favourite console text editor (you can try copying stuff back
-  and forth, but given there'll be some user switching involved you are *much*
-  better off just being able to edit things at the command line)
+* Editing a text configuration file from the Linux command line using ``nano``,
+  ``vim``, or your favourite console text editor (you can try copying stuff
+  back and forth, but given there'll be some user switching involved you are
+  *much* better off just being able to edit things at the command line)
 
 
 Shopping List
@@ -35,48 +35,52 @@ way:
 
 * A WiFi capable network
 
-* A Raspberry Pi; I'm using a `3B+`_ but any model [#pi5]_ with a CSI camera
-  port should work
+* A Raspberry Pi; I'm using a `3B+`_ but any model [#pi5]_ with a :term:`CSI`
+  camera port should work
 
 * A camera for your Pi; I'm using an old v1 camera module, but you can use
   later models [#v3]_ too or even a web-cam [#webcam]_
 
-* An SD card for your Pi; I'm using a spare 32GB SanDisk Ultra card
+* An :term:`SD card` for your Pi; I'm using a spare 32GB SanDisk Ultra card
 
 * A power supply for your Pi; micro-USB for models older than the 4B, USB-C for
   the 4B or later
 
 * A `Pico W`_, or some variant thereof (including a `Pico 2W`_, `Pico Plus
   2W`_, etc.); note you need a WiFi capable variant (not the bare Pico), and
-  that this project relies on the Pico's specific capabilities [#othermcu]_
+  that this project relies on the :term:`Pico`'s specific capabilities
+  [#othermcu]_
 
 * A `breadboard`_ large enough to mount your Pico and all associated wiring
 
 * A momentary push-button suitable for mounting on a breadboard
 
-* A red LED
+* A red :term:`LED`
 
 * A 330Ω resistor
 
 * `Jumper leads`_ or solid-core wire
 
-* A 5V power supply capable of driving the Pico (easy) and all your neopixels
-  (harder); a typical micro-USB supply is *not* going to cut the mustard here
-  but I'll go into more details below
+* A 5V power supply capable of driving the :term:`Pico` (easy) and all your
+  neopixels (harder); a typical micro-USB supply is *not* going to cut the
+  mustard here but I'll go into more details below
 
-* As many strands of WS2812 or APA102 compatible neopixels as you can
-  reasonably fit on your tree; note these do not have to be the same model, RGB
-  ordering, or length
+* As many strands of WS2812 or APA102 compatible :term:`neopixels <neopixel>`
+  as you can reasonably fit on your tree; note these do not have to be the same
+  model, RGB ordering, or length
 
-* Whatever attachments you need to connect your neopixels to your Pico or your
-  carrier board; if you're lucky your strands will already have compatible
-  connectors attached, if not you may need to solder and/or crimp some on
-  yourself
+* Whatever attachments you need to connect your neopixels to your :term:`Pico`
+  or your carrier board; if you're lucky your strands will already have
+  compatible connectors attached, if not you may need to solder and/or crimp
+  some on yourself
 
 * A box made of a non-flammable material large enough to house the power
   supply, breadboard, and all associated wiring
 
-* Some cable glands large enough to accommodate at least the mains cable
+* Some cable glands large enough to accommodate at least the mains cable, and
+  optionally the neopixel cables
+
+* A couple of cable ties
 
 In this tutorial I'll be using an `63-line breadboard`_ with two separate power
 rails which is probably overkill, but I don't like being cramped when wiring

docs/tutorial2.rst

@@ -3,10 +3,10 @@ I've got the Power!
 ===================
 
 The power supply requires some consideration. Neopixels typically have a
-maximum output power of 0.24W per LED (at 5V). All told I've got 150 LEDs, so
-that's a total potential output of 150 × 0.24W = 36W, plus whatever's required
-for the Pico but frankly that'll be so minimal by comparison it's not worth
-worrying about.
+maximum output power of 0.24W per :term:`LED` (at 5V). All told I've got 150
+LEDs, so that's a total potential output of 150 × 0.24W = 36W, plus whatever's
+required for the Pico but frankly that'll be so minimal by comparison it's not
+worth worrying about.
 
 At 5V that's 36W ÷ 5V = 7.2A which is *way* beyond the maximum output of the
 typical micro-USB power supply used with Picos; these often top out at 1A or
@@ -49,7 +49,7 @@ this! The first year I got this working, I used 150 LEDs, as we are in this
 tutorial. The next year, I scaled it up to 250 LEDs thinking "there's more than
 enough headroom in the power supply", but not considering the heating situation
 on the 5V side of things. 250 × 0.24W = 60W. 60W ÷ 5V = 12A. Pushing 12A
-through 24AWG cable causes things to get *hot*:
+through 24:term:`AWG` cable causes things to get *hot*:
 
 .. image:: images/el_scorchio.*
     :align: center

docs/tutorial3.rst

@@ -8,8 +8,8 @@ because it's what I'm more familiar with [#job]_. More specifically, I'll be
 using the 32-bit armhf variant of 22.04 because the legacy camera stack doesn't
 work on arm64 [#raspios]_ or on the later versions of Ubuntu.
 
-#. Insert your SD card into your computer, download `rpi-imager`_ (if you
-   haven't got it already), and start it.
+#. Insert your :term:`SD card` into your computer, download `rpi-imager`_ (if
+   you haven't got it already), and start it.
 
 #. Select "CHOOSE DEVICE" and pick your model of Pi from the list (I'll be
    picking "Raspberry Pi 3" which includes the 3B+).
@@ -23,11 +23,11 @@ work on arm64 [#raspios]_ or on the later versions of Ubuntu.
    about customizing the first-time configuration because we're going to do
    some of that manually to have ``cloud-init`` handle all the installation.
 
-Once the card is flashed, remove it from your computer, then re-insert it. You
-should see the boot partition (named "system-boot") appear. Open this, and look
-for the file named :file:`network-config`. Open this in your favoured text
-editor and replace the contents with the following, changing the commented
-values as appropriate:
+Once the :term:`SD card` is flashed, remove it from your computer, then
+re-insert it. You should see the boot partition (named "system-boot") appear.
+Open this, and look for the file named :file:`network-config`. Open this in
+your favoured text editor and replace the contents with the following, changing
+the commented values as appropriate:
 
 .. code-block:: yaml
     :emphasize-lines: 5,9-10
@@ -118,15 +118,15 @@ legacy camera stack [#legacy]_:
     start_x=1
     gpu_mem=128
 
-This should configure the Pi to connect to your WiFi network, import your SSH
-keys from your GitHub username [#sshkeys]_, and install everything necessary on
-the first boot. Speaking of which...
+This should configure the Pi to connect to your WiFi network, import your
+:term:`SSH` keys from your GitHub username [#sshkeys]_, and install everything
+necessary on the first boot. Speaking of which...
 
 
 First boot
 ==========
 
-#. Eject the SD card from your computer, and insert it in your Pi
+#. Eject the :term:`SD card` from your computer, and insert it in your Pi
 
 #. Connect the camera module to your Pi