Add a Python virtual environment setup

Makefile

@@ -1,5 +1,5 @@
 .PHONY: default check-archive check-tutorial check clean tidy \
-	exercises rebuild tutorial
+	exercises rebuild tutorial setup-env
 
 MAKEFILE_DIR:=$(dir $(realpath $(lastword $(MAKEFILE_LIST))))
 
@@ -202,13 +202,16 @@ _temp/consistent/% : %
 ##############################################################################
 # Tutorial document
 
+setup-env:
+	scripts/setup_env.sh
+
 # BCP: Added the --quiet flag to suppress a bunch of INFO messages
 # that the macros plugin was generating on every compile
-tutorial: rebuild
-	mkdocs build --strict --quiet
+tutorial: rebuild setup-env
+	. .venv/bin/activate && mkdocs build --strict --quiet
 
-serve: rebuild
-	mkdocs serve --quiet
+serve: rebuild setup-env
+	. .venv/bin/activate && mkdocs serve --quiet
 
 rebuild: exercises docs/exercises.zip mkdocs.yml $(shell find docs -type f)
 

README.md

@@ -19,15 +19,27 @@ The CN tutorial is built using [Material for
 MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
 Dependencies:
-* python 3.x
-* pip
+* python >=3.10
 
-```bash
-# Install Material for MkDocs
-pip install mkdocs-material mkdocs-macros-plugin
+A suitable Python virtual environment can be created by running:
+
+```console
+> scripts/setup_env.sh
+```
+
+This script only needs to be run once.
+
+It will create a `.venv/` with the dependencies necessary to build the CN
+tutorial, which can be activated with:
 
-# Build the tutorial
-make
+```console
+> source .venv/bin/activate
+```
+
+From here, building the tutorial is straightforward:
+
+```console
+> make
 ```
 
 If you are _developing_ tutorial documentation, you may wish to include
@@ -40,6 +52,9 @@ unimportant, so the empty string will suffice):
 TUTORIAL_TODOS= make
 ```
 
+Running `deactivate` will "turn off" the virtual environment; it can be
+reactivated any time using the above `source .venv/bin/activate` command.
+
 ### Hosting locally
 
 You can start a local server that automatically renders changes to the tutorial

scripts/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs-material
+mkdocs-macros-plugin

scripts/setup_env.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+
+REQUIREMENTS="$(dirname $0)/requirements.txt"
+
+echo "Checking for python3..."
+if ! [ -x "$(command -v python3)" ];
+then
+    echo "Error: python3 is not installed." >&2
+    return 1
+fi
+
+if [ -d ".venv" ];
+then
+    echo "Found a '.venv' directory."
+
+    if ! [ -e .venv/bin/activate ]
+    then
+        echo -e "\033[1;33mWARNING:\033[0m '.venv/bin/activate' not found."
+        echo "Running python3 -m venv .venv to repair..."
+        python3 -m venv .venv
+    fi
+
+    # We want to check _the virtual environment's_ pip list, so activate here.
+    . .venv/bin/activate
+
+    if pip freeze -r "${REQUIREMENTS}" 2>&1 | grep -q "not installed"
+    then
+        echo -e "\033[1;33mWARNING:\033[0m 'requirements.txt' not satisfied."
+        echo "Installing dependencies..."
+        pip install -qr "${REQUIREMENTS}"
+    fi
+
+    echo -e "\033[1;32mEnvironment updated successfully!\033[0m"
+    exit
+fi
+
+echo "No '.venv' directory found."
+echo "Running python3 -m venv .venv..."
+python3 -m venv .venv
+
+. .venv/bin/activate
+
+echo "Installing dependencies..."
+pip install -qr "${REQUIREMENTS}"
+
+echo -e "\033[1;32mEnvironment created successfully!\033[0m"
+echo -e "\033[1;32mActivate it with 'source .venv/bin/activate'.\033[0m"