From 3fd559af9b5f9aa4b38cd71ac3712a54bfc096f7 Mon Sep 17 00:00:00 2001
From: Chris Phifer <cphifer@galois.com>
Date: Wed, 23 Apr 2025 13:46:52 -0700
Subject: [PATCH 1/2] Add script (and docs) to assist in Python environment
 installation.

This is an attempt to make the development of CN tutorials more straightforward,
as far as setting up the Python build is concerned.

scripts/setup_env.sh handles creating a Python virtual environment suitable for
building the tutorial (that is, with the necessary dependencies).
This script tries to be relatively smart about not doing extra work.

The README has been updated to reflect these changes.
---
 README.md                | 29 +++++++++++++++++++------
 scripts/requirements.txt |  2 ++
 scripts/setup_env.sh     | 47 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 7 deletions(-)
 create mode 100644 scripts/requirements.txt
 create mode 100755 scripts/setup_env.sh

diff --git a/README.md b/README.md
index 45f41fee..fe160042 100644
--- a/README.md
+++ b/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
diff --git a/scripts/requirements.txt b/scripts/requirements.txt
new file mode 100644
index 00000000..bba465d8
--- /dev/null
+++ b/scripts/requirements.txt
@@ -0,0 +1,2 @@
+mkdocs-material
+mkdocs-macros-plugin
diff --git a/scripts/setup_env.sh b/scripts/setup_env.sh
new file mode 100755
index 00000000..49b7cf48
--- /dev/null
+++ b/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"

From 2c627b15f3a1b65099305107f23d96a73052c175 Mon Sep 17 00:00:00 2001
From: Chris Phifer <cphifer@galois.com>
Date: Thu, 24 Apr 2025 12:14:49 -0700
Subject: [PATCH 2/2] Makefile: Add setup-env rule.

This rule simply runs scripts/setup_env.sh; more importantly, it is also a
dependency of the tutorial build/serve commands -- and the virtual environment
it creates is now used in those rules to run mkdocs in an isolated/sandboxed
manner (as was the intent behind introducing a virtual environment in the first
place).
---
 Makefile | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/Makefile b/Makefile
index d0bcf9eb..996b4f1a 100644
--- a/Makefile
+++ b/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)