generate-docs.yml

name: Generate documentation
on:
  push:
    branches:
      - master
  pull_request:
    types: [opened, synchronize, reopened, closed]

permissions:
  contents: read

jobs:
  build-and-deploy:
    name: Build and Deploy Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 240
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Cancel Previous Runs
        uses: styfle/cancel-workflow-action@d07a454dad7609a92316b57b23c9ccfd4f59af66 # 0.13.1
        with:
          access_token: ${{ github.token }}
      - name: Add Intel repository
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        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: Install Intel OneAPI
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        run: |
          sudo apt install intel-oneapi-compiler-dpcpp-cpp
          sudo apt install intel-oneapi-tbb
          sudo apt install intel-oneapi-umf
          sudo apt install hwloc
      - name: Install Lua
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        run: |
          sudo apt-get install liblua5.2-dev
      - name: Install Doxygen
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        run: |
          sudo apt-get install doxygen
      - name: Install Ninja
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        run: |
          sudo apt-get install ninja-build
      - name: Setup Python
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.10'
          architecture: x64
      - name: Install sphinx dependencies
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        shell: bash -l {0}
        run: |
          pip install numpy 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: Checkout repo
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Build dpctl+docs
        if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
        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 scripts/gen_docs.py --doxyrest-root="$(pwd)/doxyrest-2.1.2-linux-amd64" --verbose --multiversion --clean || exit 1
          python -c "import dpctl; print(dpctl.__version__)" || exit 1
          mv "$(find _skbuild -type d -path "*/cmake-install/docs/docs" | head -n 1)" ~/docs
          git clean -dfx
          git reset --hard
      - name: Publish docs
        if: ${{ !github.event.pull_request && github.ref == 'refs/heads/master' }}
        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
          pwd
          cd master
          git rm -rf ./*
          mv ~/docs/* . || exit 1
          git add .
          git config --global user.name 'github-actions[doc-deploy-bot]'
          git config --global user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com'
          git commit -m "Latest docs."
          git push tokened_docs gh-pages
      - name: Save built docs as an artifact
        if: ${{ github.event.pull_request && github.event.pull_request.head.repo.fork && github.event.action != 'closed'}}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: ${{ env.PACKAGE_NAME }} rendered documentation
          path: ~/docs

      - name: Publish pull-request docs
        if: ${{ github.event.pull_request && !github.event.pull_request.head.repo.fork && github.event.action != 'closed' }}
        env:
          PR_NUM: ${{ github.event.number }}
        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
          pwd
          [ -d "pulls/${PR_NUM}" ] && git rm -rf "pulls/${PR_NUM}"
          mkdir -p "pulls/${PR_NUM}"
          cd "pulls/${PR_NUM}"
          mv ~/docs/* .
          git add .
          git config --global user.name 'github-actions[doc-deploy-bot]'
          git config --global user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com'
          git commit -m "Docs for pull request ${PR_NUM}"
          git push tokened_docs gh-pages
      - name: Unpublish pull-request docs
        if: ${{ github.event.pull_request && !github.event.pull_request.head.repo.fork && github.event.action == 'closed' }}
        env:
          PR_NUM: ${{ github.event.number }}
        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
          pwd
          ls
          [ -d pulls ] && ls pulls && echo "This is pull/${PR_NUM}"
          [ -d "pulls/${PR_NUM}" ] && git rm -rf "pulls/${PR_NUM}"
          git config --global user.name 'github-actions[doc-deploy-bot]'
          git config --global user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com'
          git commit -m "Removing docs for closed pull request ${PR_NUM}"
          git push tokened_docs gh-pages
      - name: Comment with URL to published pull-request docs
        if: ${{ github.event.pull_request && !github.event.pull_request.head.repo.fork && github.event.action != 'closed' }}
        env:
          PR_NUM: ${{ github.event.number }}
        uses: mshick/add-pr-comment@ec328af66588ab8f77cdeb2c264f14aba45bbf59 # v3.12.0
        with:
          message: |
            View rendered docs @ https://intelpython.github.io/dpctl/pulls/${{ env.PR_NUM }}/index.html
          repo-token: ${{ secrets.GITHUB_TOKEN }}
      - name: Comment with URL about removal of PR docs
        if: ${{ github.event.pull_request && !github.event.pull_request.head.repo.fork && github.event.action == 'closed' }}
        env:
          PR_NUM: ${{ github.event.number }}
        uses: mshick/add-pr-comment@ec328af66588ab8f77cdeb2c264f14aba45bbf59 # v3.12.0
        with:
          message: |
            Deleted rendered PR docs from intelpython.github.com/dpctl, latest should be updated shortly. :crossed_fingers:
          repo-token: ${{ secrets.GITHUB_TOKEN }}