From b0dfbe71c388d1ac98e67b3616e96d7048883f15 Mon Sep 17 00:00:00 2001
From: Benjamin Kirk <benkirk@ucar.edu>
Date: Sat, 20 Jan 2024 10:21:34 -0700
Subject: [PATCH] build ReadTheDocs with pre_build rules that set up style
 links from DEPLOY_TARGET env var

---
 .readthedocs.yaml | 16 ++++++++++++++--
 Makefile          |  6 +++---
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index cd9b9232..b991c728 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -6,9 +6,21 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: "ubuntu-22.04"
+  os: ubuntu-22.04
   tools:
-    python: "mambaforge-22.9"
+    python: mambaforge-22.9
+  jobs:
+    pre_build:
+      # just nice to know what's happening up there...
+      - env | sort | uniq
+
+      # DEPLOY_TARGET is set in our readthedocs admin interface, and should
+      # be one of the supported targets: [ primary, arc_iframe ]
+      - make ${DEPLOY_TARGET}-stylelinks
+
+      # the above may generate a dirty git cache for some committed symbolic links - ignore. ref:
+      # https://docs.readthedocs.io/en/stable/build-customization.html#avoid-having-a-dirty-git-index
+      - git update-index --assume-unchanged theme.yml docs/stylesheets/custom.css
 
 conda:
   environment: conda.yaml
diff --git a/Makefile b/Makefile
index 0ee8e4a8..b07784de 100644
--- a/Makefile
+++ b/Makefile
@@ -35,8 +35,8 @@ dos2unix:
 	  dos2unix $$file ; \
 	done
 
-primary-links arc_iframe-links:
-	target=$(subst -links,,$@) ; \
+primary-stylelinks arc_iframe-stylelinks:
 	topdir=$$(pwd) ; \
+	target=$(subst -stylelinks,,$@) ; \
 	cd $${topdir} && ln -sf theme_$${target}.yml theme.yml ; \
-	cd $${topdir}//docs/stylesheets/ && ln -sf $${target}.css custom.css
+	cd $${topdir}/docs/stylesheets/ && ln -sf $${target}.css custom.css