Fix older docs builds and allow writing over existing tags

Author: ndgrigorian

.github/workflows/backfill-docs.yml

@@ -10,12 +10,18 @@ on:
         description: 'Python version to build with (default: the one recorded in the tag)'
         required: false
         type: string
+      compiler-version:
+        description: 'DPC++ version to build with (default: the one required by the tag)'
+        required: false
+        type: string
 
 permissions:
   contents: read
 
 env:
   CHECK_CONFIG_SCRIPT: "import sys; from packaging.version import parse; print('true' if parse('0.17.0') <= parse(sys.argv[1]) < parse('0.22.0') else 'false')"
+  # dpctl gained NumPy 2 support in 0.18.0dev1; earlier tags fail to build against it.
+  NUMPY_SPEC_SCRIPT: "import sys; from packaging.version import parse; print('numpy<2' if parse(sys.argv[1]) < parse('0.18.0dev1') else 'numpy')"
   # Used only for tags that predate the docs workflow and so record no version.
   DEFAULT_PYTHON_VERSION: '3.10'
 
@@ -39,9 +45,48 @@ jobs:
           echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] https://apt.repos.intel.com/oneapi all main" \
             | sudo tee /etc/apt/sources.list.d/oneAPI.list
           sudo apt update
+      - name: Checkout repo at tag
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.inputs.tag }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Resolve DPC++ version for the tag
+        id: resolve-compiler
+        env:
+          TAG: ${{ github.event.inputs.tag }}
+          COMPILER_VERSION_INPUT: ${{ github.event.inputs.compiler-version }}
+        run: |
+          COMPILER_PACKAGE=intel-oneapi-compiler-dpcpp-cpp
+
+          if [[ -n "${COMPILER_VERSION_INPUT}" ]]; then
+            COMPILER_VERSION="${COMPILER_VERSION_INPUT}"
+            echo "Using DPC++ ${COMPILER_VERSION} requested via workflow input."
+          else
+            # build against compiler version declared in the conda recipe
+            COMPILER_VERSION=$(grep -oP 'required_compiler_version\s*=\s*"\K[^"]+' \
+                               conda-recipe/meta.yaml 2>/dev/null | head -n 1 || true)
+            if [[ -z "${COMPILER_VERSION}" ]]; then
+              echo "${TAG} declares no required_compiler_version. Using the latest DPC++."
+              echo "package=${COMPILER_PACKAGE}" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "${TAG} requires DPC++ ${COMPILER_VERSION}."
+          fi
+
+          VERSIONED_PACKAGE="${COMPILER_PACKAGE}-$(cut -d. -f1,2 <<< "${COMPILER_VERSION}")"
+          if apt-cache show "${VERSIONED_PACKAGE}" > /dev/null 2>&1; then
+            COMPILER_PACKAGE="${VERSIONED_PACKAGE}"
+            echo "Installing ${COMPILER_PACKAGE}."
+          else
+            echo "::warning::${VERSIONED_PACKAGE} is not in the Intel apt repository. Using the latest DPC++ instead."
+          fi
+          echo "package=${COMPILER_PACKAGE}" >> "$GITHUB_OUTPUT"
       - name: Install Intel OneAPI
+        env:
+          COMPILER_PACKAGE: ${{ steps.resolve-compiler.outputs.package }}
         run: |
-          sudo apt install intel-oneapi-compiler-dpcpp-cpp
+          sudo apt install "${COMPILER_PACKAGE}"
           sudo apt install intel-oneapi-tbb
           sudo apt install intel-oneapi-umf
           sudo apt install hwloc
@@ -54,12 +99,6 @@ jobs:
       - name: Install Ninja
         run: |
           sudo apt-get install ninja-build
-      - name: Checkout repo at tag
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          ref: ${{ github.event.inputs.tag }}
-          fetch-depth: 0
-          persist-credentials: false
       - name: Resolve Python version for the tag
         id: resolve-python
         env:
@@ -88,8 +127,13 @@ jobs:
           architecture: x64
       - name: Install sphinx dependencies
         shell: bash -l {0}
+        env:
+          TAG: ${{ github.event.inputs.tag }}
         run: |
-          pip install numpy cython setuptools">=70.1" scikit-build cmake sphinx"<7.2" pydot graphviz furo \
+          pip install packaging
+          NUMPY_SPEC=$(python -c "$NUMPY_SPEC_SCRIPT" "$TAG")
+          echo "Building against ${NUMPY_SPEC}."
+          pip install "${NUMPY_SPEC}" cython setuptools">=70.1" scikit-build cmake sphinx"<7.2" pydot graphviz furo \
                       sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx-design \
                       sphinxcontrib-jsmath sphinx-copybutton sphinxcontrib-spelling \
                       versioneer[toml]==0.29
@@ -98,13 +142,18 @@ jobs:
         env:
           TAG: ${{ github.event.inputs.tag }}
         run: |
-          NEEDS_CONFIG=$(python -c "$CHECK_CONFIG_SCRIPT" "$TAG")
+          git fetch origin master
+
+          # a tag cannot list the versions released after it, so the version list
+          # behind the sidebar dropdown always has to come from master
+          git checkout origin/master -- docs/doc_versions.txt
 
+          NEEDS_CONFIG=$(python -c "$CHECK_CONFIG_SCRIPT" "$TAG")
           if [[ "${NEEDS_CONFIG}" == "true" ]]; then
-            git fetch origin master
-            git checkout origin/master -- docs/doc_sources/conf.py.in docs/doc_sources/_templates/versions.html docs/doc_versions.txt
+            git checkout origin/master -- docs/doc_sources/conf.py.in \
+                                          docs/doc_sources/_templates/versions.html
           else
-            echo "Version does not require docs config injection."
+            echo "Tag already has the current docs template, only the version list was injected."
           fi
       - name: Build dpctl+docs
         shell: bash -l {0}
@@ -138,10 +187,10 @@ jobs:
           git remote add tokened_docs https://IntelPython:${{ secrets.GITHUB_TOKEN }}@github.com/IntelPython/dpctl.git
           git fetch tokened_docs
           git checkout --track tokened_docs/gh-pages
-          [ -d "${TAG}" ] || mkdir "${TAG}"
-           rm -rf "${TAG:?}/*"
-          mv ~/docs/* "${TAG}/" || exit 1
-          git add "${TAG}"
+          # replace the directory outright so a re-run cannot merge into stale docs
+          rm -rf "${TAG:?}"
+          mv ~/docs "${TAG}" || exit 1
+          git add --all "${TAG}"
           git config user.name 'github-actions[doc-deploy-bot]'
           git config user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com'
           git commit -m "Docs backfilled for ${TAG}."