From fbb8b7d24bd4dbb953d3f5870ce4554a69003f9f Mon Sep 17 00:00:00 2001
From: Liam Girdwood <liam.r.girdwood@intel.com>
Date: Sat, 1 Mar 2025 19:14:40 +0000
Subject: [PATCH 1/2] scripts: gen-doc: enforce python virtual environment

System tools for sphinx etc tend to be behind the versions available
via pip. Prefer the pip version and automatically enable the Python
virtual environment when starting the script.

Signed-off-by: Liam Girdwood <liam.r.girdwood@intel.com>
---
 scripts/gen-doc.sh | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/scripts/gen-doc.sh b/scripts/gen-doc.sh
index 489dce9cbb2c..2dc1a34d4b60 100755
--- a/scripts/gen-doc.sh
+++ b/scripts/gen-doc.sh
@@ -6,8 +6,25 @@
 # According to instructions:
 # https://thesofproject.github.io/latest/howtos/process/docbuild.html
 
-# fail immediately on any errors
-set -e
+# this needs to run from the Zephyr python virtual environment
+# so that the python packages are available (and more up to date than
+# the system packages).
+
+# check if Zephyr environment is set up
+if [ ! -z "$ZEPHYR_BASE" ]; then
+    VENV_DIR="$ZEPHYR_BASE/.venv"
+    echo "Using Zephyr environment at $ZEPHYR_BASE"
+elif [ ! -z "$SOF_WORKSPACE" ]; then
+    VENV_DIR="$SOF_WORKSPACE/zephyr/.venv"
+    echo "Using SOF/Zephyr environment at $SOF_WORKSPACE"
+else
+    # fallback to the zephyr default from the getting started guide
+    VENV_DIR="$HOME/zephyrproject/.venv"
+    echo "Using default Zephyr environment at $VENV_DIR"
+fi
+
+# start the virtual environment
+source ${VENV_DIR}/bin/activate
 
 function print_usage()
 {
@@ -133,3 +150,6 @@ then
 	cd "$DOCS_REPO"
 	make publish
 fi
+
+# cleanup
+deactivate

From 3e3ce61903f13b76a2b685a1edfde276c6a13f0d Mon Sep 17 00:00:00 2001
From: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Date: Sat, 8 Mar 2025 18:44:19 +0000
Subject: [PATCH 2/2] scripts: gen-doc: move all build output of source
 directory.

Move the intermediate doxygen build output out of the source directory.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
---
 scripts/gen-doc.sh | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/scripts/gen-doc.sh b/scripts/gen-doc.sh
index 2dc1a34d4b60..7b36c0da96d6 100755
--- a/scripts/gen-doc.sh
+++ b/scripts/gen-doc.sh
@@ -38,11 +38,11 @@ function print_usage()
 # make it runnable from any location
 # user shouldn't be confused from which dir this script has to be run
 SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
-
 # expected paths of repositories needed for documentation process
 SOF_REPO=$(dirname "$SCRIPT_DIR")
 DOCS_REPO="$(dirname "$SOF_REPO")/sof-docs"
 PUBLISH_REPO="$(dirname "$SOF_REPO")/thesofproject.github.io"
+BUILD_DIR="$(dirname "$SOF_REPO")/build-sof-docs"
 
 # parse arguments
 DO_BUILD=false
@@ -90,12 +90,10 @@ then
 	fi
 fi
 
-cd "$SOF_REPO/doc"
-
 if "$DO_CLEAN"
 then
 	echo "Cleaning $SOF_REPO"
-	cmake .
+	cd ${BUILD_DIR}
 	make clean
 	make doc-clean
 fi
@@ -103,7 +101,8 @@ fi
 if "$DO_BUILD"
 then
 	echo "Building $SOF_REPO"
-	cmake .
+	cd "$SOF_REPO/doc"
+	cmake -S . -B ${BUILD_DIR}
 	make doc
 fi