backfill-docs.yml

name: Backfill documentation
on:
  workflow_dispatch:
    inputs:
      tag:
        description: 'Tag to backfill from'
        required: true
        type: string
      python-version:
        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'

jobs:
  build-and-backfill:
    name: Build and Backfill Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 240
    permissions:
      contents: write
      actions: write
    steps:
      - name: Cancel Previous Runs
        uses: styfle/cancel-workflow-action@d07a454dad7609a92316b57b23c9ccfd4f59af66 # 0.13.1
        with:
          access_token: ${{ github.token }}
      - name: Add Intel repository
        run: |
          wget -qO- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \
            | gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null
          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 "${COMPILER_PACKAGE}"
          sudo apt install intel-oneapi-tbb
          sudo apt install intel-oneapi-umf
          sudo apt install hwloc
      - name: Install Lua
        run: |
          sudo apt-get install liblua5.2-dev
      - name: Install Doxygen
        run: |
          sudo apt-get install doxygen
      - name: Install Ninja
        run: |
          sudo apt-get install ninja-build
      - name: Resolve Python version for the tag
        id: resolve-python
        env:
          TAG: ${{ github.event.inputs.tag }}
          PYTHON_VERSION_INPUT: ${{ github.event.inputs.python-version }}
        run: |
          if [[ -n "${PYTHON_VERSION_INPUT}" ]]; then
            PYTHON_VERSION="${PYTHON_VERSION_INPUT}"
            echo "Using Python ${PYTHON_VERSION} requested via workflow input."
          else
            # reuse pin from generate-docs.yml at the tag
            PYTHON_VERSION=$(grep -oP "python-version:\s*'?\K[0-9]+\.[0-9]+" \
                             .github/workflows/generate-docs.yml 2>/dev/null | head -n 1 || true)
            if [[ -z "${PYTHON_VERSION}" ]]; then
              PYTHON_VERSION="${DEFAULT_PYTHON_VERSION}"
              echo "${TAG} records no docs Python version; falling back to ${PYTHON_VERSION}."
            else
              echo "Using Python ${PYTHON_VERSION} as recorded at ${TAG}."
            fi
          fi
          echo "python-version=${PYTHON_VERSION}" >> "$GITHUB_OUTPUT"
      - name: Setup Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ steps.resolve-python.outputs.python-version }}
          architecture: x64
      - name: Install sphinx dependencies
        shell: bash -l {0}
        env:
          TAG: ${{ github.event.inputs.tag }}
        run: |
          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
      - name: Inject new docs configuration
        shell: bash -l {0}
        env:
          TAG: ${{ github.event.inputs.tag }}
        run: |
          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 checkout origin/master -- docs/doc_sources/conf.py.in \
                                          docs/doc_sources/_templates/versions.html
          else
            echo "Tag already has the current docs template, only the version list was injected."
          fi
      - name: Build dpctl+docs
        shell: bash -l {0}
        run: |
          # Ensure that SYCL libraries are on LD_LIBRARY_PATH
          source /opt/intel/oneapi/setvars.sh
          wget https://github.com/vovkos/doxyrest/releases/download/doxyrest-2.1.2/doxyrest-2.1.2-linux-amd64.tar.xz
          tar xf doxyrest-2.1.2-linux-amd64.tar.xz
          python setup.py build_ext --inplace --generator=Ninja --build-type=Release \
              --                                                                     \
              -DCMAKE_C_COMPILER:PATH="$(which icx)"                                 \
              -DCMAKE_CXX_COMPILER:PATH="$(which icpx)"                              \
              -DDPCTL_GENERATE_DOCS=ON                                               \
              -DDPCTL_ENABLE_DOXYREST=ON                                             \
              -DDPCTL_USE_MULTIVERSION_TEMPLATE=ON                                   \
              -DDoxyrest_DIR="$(pwd)/doxyrest-2.1.2-linux-amd64"                     \
              -DCMAKE_VERBOSE_MAKEFILE=ON
          python -m pip install -e . --no-build-isolation --no-deps
          python -c "import dpctl; print(dpctl.__version__)" || exit 1
          pushd "$(find _skbuild -name cmake-build)" || exit 1
          cmake --build . --target Sphinx || exit 1
          mv ../cmake-install/docs/docs ~/docs
          git clean -dfx
          popd
          git reset --hard
      - name: Publish docs
        env:
          TAG: ${{ github.event.inputs.tag }}
        shell: bash -l {0}
        run: |
          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
          # 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}."
          git push tokened_docs gh-pages