From ba89671c16fdd9c7e68f5ba9c71bda6416c1068f Mon Sep 17 00:00:00 2001
From: Ryan Johnson <ryan@tenthirtyam.org>
Date: Mon, 31 Aug 2026 14:28:24 -0400
Subject: [PATCH] chore: update makefile

Update `Makefile` for documentation publications.

Signed-off-by: Ryan Johnson <ryan.johnson@broadcom.com>
---
 Makefile                          | 16 ++++++++++++++--
 docs-site/scripts/lib/mike-env.sh | 16 ++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index ca434dab..677e300c 100644
--- a/Makefile
+++ b/Makefile
@@ -38,10 +38,22 @@ generate: install-packer-sdc
 DOCS_VENV?=$(CURDIR)/docs-site/.venv
 DOCS_PYTHON=$(DOCS_VENV)/bin/python
 DOCS_PIP=$(DOCS_VENV)/bin/pip
+DOCS_BOOTSTRAP_PYTHON ?= $(shell command -v python3.14 || command -v python3.13 || command -v python3.12 || command -v python3.11 || command -v python3.10 || true)
 
 docs-deps:
-	@test -d "$(DOCS_VENV)" || python3 -m venv "$(DOCS_VENV)"
-	@"$(DOCS_PIP)" install -r docs-site/requirements.txt
+	@bootstrap="$(DOCS_BOOTSTRAP_PYTHON)"; \
+	if [ -z "$$bootstrap" ]; then \
+		echo "error: Python 3.10+ is required for zensical (python3 is $$(python3 -V 2>/dev/null || echo missing))" >&2; \
+		echo "hint: brew install python && make docs-deps" >&2; \
+		exit 1; \
+	fi; \
+	if [ -x "$(DOCS_PYTHON)" ] && ! "$(DOCS_PYTHON)" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)'; then \
+		echo "Recreating docs-site/.venv with $$("$$bootstrap" -V) (zensical requires Python 3.10+)"; \
+		rm -rf "$(DOCS_VENV)"; \
+	fi; \
+	test -d "$(DOCS_VENV)" || "$$bootstrap" -m venv "$(DOCS_VENV)"; \
+	"$(DOCS_PYTHON)" -m pip install --upgrade pip; \
+	"$(DOCS_PIP)" install -r docs-site/requirements.txt
 
 docs-prepare:
 	@./docs-site/scripts/prepare-docs.sh
diff --git a/docs-site/scripts/lib/mike-env.sh b/docs-site/scripts/lib/mike-env.sh
index b80f98c8..18cb0237 100755
--- a/docs-site/scripts/lib/mike-env.sh
+++ b/docs-site/scripts/lib/mike-env.sh
@@ -14,14 +14,26 @@ source "${LIB_DIR}/paths.sh"
 resolve_mike() {
   MIKE="${DOCS_SITE_DIR}/.venv/bin/mike"
   if [[ ! -x "$MIKE" ]]; then
-    MIKE="$(command -v mike)"
+    MIKE="$(command -v mike || true)"
   fi
+  if [[ -z "${MIKE:-}" || ! -x "$MIKE" ]]; then
+    echo "error: mike not found; run: make docs-deps" >&2
+    exit 1
+  fi
+  # mike invokes zensical by name; keep the venv bin first on PATH.
+  local bindir
+  bindir="$(cd "$(dirname "$MIKE")" && pwd)"
+  export PATH="${bindir}:${PATH}"
 }
 
 resolve_zensical() {
   ZENSICAL="${DOCS_SITE_DIR}/.venv/bin/zensical"
   if [[ ! -x "$ZENSICAL" ]]; then
-    ZENSICAL="$(command -v zensical)"
+    ZENSICAL="$(command -v zensical || true)"
+  fi
+  if [[ -z "${ZENSICAL:-}" || ! -x "$ZENSICAL" ]]; then
+    echo "error: zensical not found; run: make docs-deps" >&2
+    exit 1
   fi
 }