From 8d80de598a970381281ee5aa596336d1a9f0a24e Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Wed, 8 Mar 2023 16:29:45 +0800
Subject: [PATCH 1/4] Add python version search script

---
 tools/get-best-python-for-docs-build.sh | 33 +++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100755 tools/get-best-python-for-docs-build.sh

diff --git a/tools/get-best-python-for-docs-build.sh b/tools/get-best-python-for-docs-build.sh
new file mode 100755
index 00000000..3bd15be5
--- /dev/null
+++ b/tools/get-best-python-for-docs-build.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+# This script prints the version suffix of the most suitable version of Python
+# for building docs that's installed in this system.
+#
+# Caller can safely append this suffix to `python` or `pip` and expect the
+# binary to exist.
+#
+# If no usable version of Python is available, this script will exit with a
+# non-zero code.
+
+set -e
+
+# if `python3` is >= 3.8 and `pip3` is available, use that
+if echo -e "import sys\nif sys.version_info < (3,8):\n exit(1)" | python3 && \
+which pip3 1>/dev/null 2>&1; then
+    echo "3"
+    exit 0
+fi
+
+# check `python3.N` from newest to oldest
+CANDIDATE_SUFFIXES=("3.11" "3.10" "3.9" "3.8")
+for SUFFIX in ${CANDIDATE_SUFFIXES[@]}; do
+    # if both `python3.N` and `pip3.N` are available, use that
+    if which "python$SUFFIX" 1>/dev/null 2>&1 && \
+    which "pip$SUFFIX" 1>/dev/null 2>&1; then
+        echo "$SUFFIX"
+        exit 0
+    fi
+done
+
+# none found
+exit 1

From f95979586d489be6bb538dd89c1b1f21c1a3a204 Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Wed, 8 Mar 2023 16:30:18 +0800
Subject: [PATCH 2/4] Update Makefile to use script

---
 Makefile | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/Makefile b/Makefile
index 8ca86dae..847c34af 100644
--- a/Makefile
+++ b/Makefile
@@ -96,25 +96,28 @@ build-deps-ubuntu:
 docs: docs-deps docs-build
 
 docs-build: .PHONY
-	@if ! /bin/echo -e "import sys\nif sys.version_info < (3,8):\n exit(1)" | python3; then \
-	  if which python3.8; then \
-	  	echo "python3.8 $(shell which mkdocs) build"; \
-	    python3.8 $(shell which mkdocs) build; \
-	  else \
-	    echo "ERROR: Python version too low. mkdocs-material needs >= 3.8"; \
-	    exit 1; \
-	  fi; \
-	else \
-	  echo "mkdocs build"; \
-	  mkdocs build; \
-	fi
+	@if ! SUFFIX=$$(tools/get-best-python-for-docs-build.sh); then \
+		echo "ERROR: could not find a recent version of Python. mkdocs needs >= 3.8"; \
+		exit 1; \
+	fi; \
+	echo "python$$SUFFIX $$(which mkdocs) build"; \
+	"python$$SUFFIX" $$(which mkdocs) build
 
 docs-deps: .PHONY
-	pip3 install -r requirements.txt
+	@if ! SUFFIX=$$(tools/get-best-python-for-docs-build.sh); then \
+		echo "ERROR: could not find a recent version of Python. mkdocs needs >= 3.8"; \
+		exit 1; \
+	fi; \
+	echo "pip$$SUFFIX install -r requirements.txt"; \
+	"pip$$SUFFIX" install -r requirements.txt
 
 docs-deps-update: .PHONY
-	pip3 install -r requirements.txt --upgrade
-
+	@if ! SUFFIX=$$(tools/get-best-python-for-docs-build.sh); then \
+		echo "ERROR: could not find a recent version of Python. mkdocs needs >= 3.8"; \
+		exit 1; \
+	fi; \
+	echo "pip$$SUFFIX install -r requirements.txt --upgrade"; \
+	"pip$$SUFFIX" install -r requirements.txt --upgrade
 
 # Web app
 

From d44570b557cc2bc8367f4f8727187b858c98916c Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Tue, 14 Mar 2023 16:56:20 +0800
Subject: [PATCH 3/4] Script returns full binary name

---
 Makefile                                      | 24 +++++------------
 ...on-for-docs-build.sh => get-python-bin.sh} | 26 ++++++++++++++-----
 2 files changed, 25 insertions(+), 25 deletions(-)
 rename tools/{get-best-python-for-docs-build.sh => get-python-bin.sh} (63%)

diff --git a/Makefile b/Makefile
index 847c34af..77b5c5a3 100644
--- a/Makefile
+++ b/Makefile
@@ -96,28 +96,16 @@ build-deps-ubuntu:
 docs: docs-deps docs-build
 
 docs-build: .PHONY
-	@if ! SUFFIX=$$(tools/get-best-python-for-docs-build.sh); then \
-		echo "ERROR: could not find a recent version of Python. mkdocs needs >= 3.8"; \
-		exit 1; \
-	fi; \
-	echo "python$$SUFFIX $$(which mkdocs) build"; \
-	"python$$SUFFIX" $$(which mkdocs) build
+	PY=$$(tools/get-python-bin.sh python) && MKDOCS=$$(which mkdocs) && \
+	$$PY $$MKDOCS build
 
 docs-deps: .PHONY
-	@if ! SUFFIX=$$(tools/get-best-python-for-docs-build.sh); then \
-		echo "ERROR: could not find a recent version of Python. mkdocs needs >= 3.8"; \
-		exit 1; \
-	fi; \
-	echo "pip$$SUFFIX install -r requirements.txt"; \
-	"pip$$SUFFIX" install -r requirements.txt
+	PIP=$$(tools/get-python-bin.sh pip) && \
+	$$PIP install -r requirements.txt
 
 docs-deps-update: .PHONY
-	@if ! SUFFIX=$$(tools/get-best-python-for-docs-build.sh); then \
-		echo "ERROR: could not find a recent version of Python. mkdocs needs >= 3.8"; \
-		exit 1; \
-	fi; \
-	echo "pip$$SUFFIX install -r requirements.txt --upgrade"; \
-	"pip$$SUFFIX" install -r requirements.txt --upgrade
+	PIP=$$(tools/get-python-bin.sh pip) && \
+	$$PIP install -r requirements.txt --upgrade
 
 # Web app
 
diff --git a/tools/get-best-python-for-docs-build.sh b/tools/get-python-bin.sh
similarity index 63%
rename from tools/get-best-python-for-docs-build.sh
rename to tools/get-python-bin.sh
index 3bd15be5..13cce1e0 100755
--- a/tools/get-best-python-for-docs-build.sh
+++ b/tools/get-python-bin.sh
@@ -1,20 +1,31 @@
 #!/usr/bin/env bash
 
-# This script prints the version suffix of the most suitable version of Python
-# for building docs that's installed in this system.
+# Synopsis:
+# - get-python-bin.sh python
+# - get-python-bin.sh pip
 #
-# Caller can safely append this suffix to `python` or `pip` and expect the
-# binary to exist.
+# This script selects the most suitable `python` / `pip` binary available
+# for building docs that's installed in this system.
 #
 # If no usable version of Python is available, this script will exit with a
 # non-zero code.
 
 set -e
 
+case "$1" in
+    "python" | "pip")
+        BIN_PREFIX="$1"
+        ;;
+    *)
+        echo "Incorrect usage" >&2
+        exit 1
+        ;;
+esac
+
 # if `python3` is >= 3.8 and `pip3` is available, use that
 if echo -e "import sys\nif sys.version_info < (3,8):\n exit(1)" | python3 && \
 which pip3 1>/dev/null 2>&1; then
-    echo "3"
+    echo "${BIN_PREFIX}3"
     exit 0
 fi
 
@@ -24,10 +35,11 @@ for SUFFIX in ${CANDIDATE_SUFFIXES[@]}; do
     # if both `python3.N` and `pip3.N` are available, use that
     if which "python$SUFFIX" 1>/dev/null 2>&1 && \
     which "pip$SUFFIX" 1>/dev/null 2>&1; then
-        echo "$SUFFIX"
+        echo "${BIN_PREFIX}${SUFFIX}"
         exit 0
     fi
 done
 
 # none found
-exit 1
+echo "No suitable version of Python found" >&2
+exit 2

From 008ff709c820e50cb45c85ab7da52f665b819484 Mon Sep 17 00:00:00 2001
From: cyqsimon <28627918+cyqsimon@users.noreply.github.com>
Date: Wed, 12 Jul 2023 18:44:04 +0800
Subject: [PATCH 4/4] Improve python binary selection logic

- Check all available versions of python3 instead of just the shortlist
- Allow manually overriding using make variables
---
 Makefile                | 13 +++++++------
 tools/get-python-bin.sh | 13 +++++++------
 2 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/Makefile b/Makefile
index 77b5c5a3..548c23ee 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,11 @@
 MAKEFLAGS := --jobs=1
+
 VERSION := $(shell git describe --tag)
 COMMIT := $(shell git rev-parse --short HEAD)
 
+PY_BIN := $(shell tools/get-python-bin.sh python)
+PIP_BIN := $(shell tools/get-python-bin.sh pip)
+
 .PHONY:
 
 help:
@@ -96,16 +100,13 @@ build-deps-ubuntu:
 docs: docs-deps docs-build
 
 docs-build: .PHONY
-	PY=$$(tools/get-python-bin.sh python) && MKDOCS=$$(which mkdocs) && \
-	$$PY $$MKDOCS build
+	PY=$$(which $(PY_BIN)) && MKDOCS=$$(which mkdocs) && $$PY $$MKDOCS build
 
 docs-deps: .PHONY
-	PIP=$$(tools/get-python-bin.sh pip) && \
-	$$PIP install -r requirements.txt
+	PIP=$$(which $(PIP_BIN)) && $$PIP install -r requirements.txt
 
 docs-deps-update: .PHONY
-	PIP=$$(tools/get-python-bin.sh pip) && \
-	$$PIP install -r requirements.txt --upgrade
+	PIP=$$(which $(PIP_BIN)) && $$PIP install -r requirements.txt --upgrade
 
 # Web app
 
diff --git a/tools/get-python-bin.sh b/tools/get-python-bin.sh
index 13cce1e0..8c0eb857 100755
--- a/tools/get-python-bin.sh
+++ b/tools/get-python-bin.sh
@@ -29,13 +29,14 @@ which pip3 1>/dev/null 2>&1; then
     exit 0
 fi
 
-# check `python3.N` from newest to oldest
-CANDIDATE_SUFFIXES=("3.11" "3.10" "3.9" "3.8")
-for SUFFIX in ${CANDIDATE_SUFFIXES[@]}; do
+# list all available `python3.N`, then use the newest that passes checks
+# compgen is bash-specific, but we asked for bash in shebang so it's fine
+MINOR_VERSION_CANDIDATES=$(compgen -c | grep -P '^python3\.[0-9]+$' | sed 's/python3\.//' | awk 'int($NF) >= 8' | sort -nr)
+for MINOR in ${MINOR_VERSION_CANDIDATES[@]}; do
     # if both `python3.N` and `pip3.N` are available, use that
-    if which "python$SUFFIX" 1>/dev/null 2>&1 && \
-    which "pip$SUFFIX" 1>/dev/null 2>&1; then
-        echo "${BIN_PREFIX}${SUFFIX}"
+    if which "python3.${MINOR}" 1>/dev/null 2>&1 && \
+    which "pip3.${MINOR}" 1>/dev/null 2>&1; then
+        echo "${BIN_PREFIX}3.${MINOR}"
         exit 0
     fi
 done