build-sphinx.yml

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

permissions: read-all

env:
  GH_BOT_NAME: 'github-actions[bot]'
  GH_BOT_EMAIL: 'github-actions[bot]@users.noreply.github.com'
  GH_EVENT_OPEN_PR_UPSTREAM: ${{ github.event_name == 'pull_request' && github.event.action != 'closed' &&
                                 github.event.pull_request && !github.event.pull_request.base.repo.fork }}
  GH_EVENT_PUSH_UPSTREAM: ${{ github.ref == 'refs/heads/master' && github.event_name == 'push' &&
                              github.event.ref == 'refs/heads/master' && github.event.repository && !github.event.repository.fork }}
  PUBLISH_DIR: doc/_build/html/

defaults:
  run:
    shell: bash -el {0}

jobs:
  build-and-deploy:
    name: Build and Deploy Docs

    runs-on: ubuntu-latest

    permissions:
      # Needed to cancel any previous runs that are not completed for a given workflow
      actions: write
      # Needed to deploy static files to GitHub Pages
      contents: write
      # Needed to add a comment to a pull request's issue
      pull-requests: write

    env:
      python-ver: '3.12'
      CHANNELS: '-c dppy/label/dev -c intel -c conda-forge --override-channels'
      NO_INTEL_CHANNELS: '-c dppy/label/dev -c conda-forge --override-channels'
      # Install the latest oneAPI compiler to work around an issue
      INSTALL_ONE_API: 'yes'

    steps:
      - name: Cancel Previous Runs
        uses: styfle/cancel-workflow-action@85880fa0301c86cca9da44039ee3bb12d3bedbfa # 0.12.1
        with:
          access_token: ${{ github.token }}

      - name: Dump GitHub context
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
        run: |
          echo "$GITHUB_CONTEXT"

      - name: Free Disk Space (Ubuntu)
        uses: jlumbroso/free-disk-space@54081f138730dfa15788a46383842cd2f914a1be # v1.3.1
        with:
          docker-images: false

      - name: Add Intel repository
        run: |
          wget https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
          cat GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null
          rm GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB
          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: Update libstdc++-dev
        run: |
          sudo apt remove -y gcc-7 g++-7 gcc-8 g++-8 gcc-10 g++-10
          sudo apt remove -y libstdc++-10-dev
          sudo apt autoremove
          sudo apt install --reinstall -y gcc-9 g++-9 libstdc++-9-dev

      - name: Install Intel OneAPI
        run: |
          sudo apt install hwloc                           \
                           intel-oneapi-mkl                \
                           intel-oneapi-umf                \
                           intel-oneapi-mkl-devel          \
                           intel-oneapi-tbb-devel          \
                           intel-oneapi-libdpstd-devel     \
                           intel-oneapi-compiler-dpcpp-cpp

      # required by sphinxcontrib-spelling extension
      - name: Install enchant package
        run: |
          sudo apt-get install enchant-2

      # https://github.com/marketplace/actions/checkout
      - name: Install nvidia-cuda support drivers
        run: |
          sudo add-apt-repository ppa:graphics-drivers/ppa
          sudo apt-get update
          sudo apt-get install -y libnvidia-gl-450
          sudo apt-get install -y nvidia-cuda-toolkit clinfo

      - name: Checkout repo
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0

      # https://github.com/marketplace/actions/setup-miniconda
      - name: Setup miniconda
        uses: conda-incubator/setup-miniconda@d2e6a045a86077fb6cad6f5adf368e9076ddaa8d # v3.1.0
        with:
          miniforge-version: latest
          use-mamba: 'true'
          channels: conda-forge
          conda-remove-defaults: 'true'
          python-version: ${{ env.python-ver }}
          activate-environment: 'docs'

      # Sometimes `mamba install ...` fails due to slow download speed rate, so disable the check in mamba
      - name: Disable speed limit check in mamba
        run: echo "MAMBA_NO_LOW_SPEED_LIMIT=1" >> $GITHUB_ENV

      - name: Install sphinx dependencies
        run: |
          mamba install sphinx sphinx_rtd_theme
          pip install sphinxcontrib-googleanalytics==0.4 \
            pyenchant sphinxcontrib-spelling

      - name: Install dpnp dependencies
        if: env.INSTALL_ONE_API == 'yes'
        run: |
          mamba install numpy dpctl">=0.18.0dev0" cmake cython pytest ninja scikit-build ${{ env.NO_INTEL_CHANNELS }}

      - name: Install dpnp dependencies
        if: env.INSTALL_ONE_API != 'yes'
        run: |
          mamba install numpy dpctl">=0.18.0dev0" mkl-devel-dpcpp onedpl-devel tbb-devel dpcpp_linux-64 \
              cmake cython pytest ninja scikit-build ${{ env.CHANNELS }}

      - name: Install cuPy dependencies
        run: mamba install cupy

      - name: Conda info
        run: mamba info

      - name: Conda list
        run: mamba list

      - name: Build library
        run: |
          [ -f /opt/intel/oneapi/setvars.sh ] && source /opt/intel/oneapi/setvars.sh
          python scripts/build_locally.py

      - name: Run a spelling checker for docs
        run: |
          [ -f /opt/intel/oneapi/setvars.sh ] && source /opt/intel/oneapi/setvars.sh
          make spelling
        working-directory: doc

      - name: Build docs
        run: |
          [ -f /opt/intel/oneapi/setvars.sh ] && source /opt/intel/oneapi/setvars.sh
          make html
        working-directory: doc

      - name: Set a project number to current release
        run: |
          export PROJECT_NUMBER=$(git describe --tags --abbrev=0)

          echo PROJECT_NUMBER=${PROJECT_NUMBER}
          echo "PROJECT_NUMBER=$PROJECT_NUMBER" >> $GITHUB_ENV

      # https://github.com/marketplace/actions/doxygen-action
      - name: Build backend docs
        uses: mattnotmitt/doxygen-action@cbe72c8e402e8a3faa1f0b247ef90aa6c8e4ce74 # v1.9.8
        with:
            working-directory: 'dpnp/backend/doc'

      - name: Copy backend docs
        run: cp -r dpnp/backend/doc/html ${{ env.PUBLISH_DIR }}/backend_doc

      # https://github.com/marketplace/actions/github-pages-action
      # The step is only used to build docs while pushing a PR to "master"
      - name: Deploy docs
        if: env.GH_EVENT_PUSH_UPSTREAM == 'true'
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ${{ env.PUBLISH_DIR }}
          keep_files: true
          commit_message: ${{ github.event.head_commit.message }}
          publish_branch: gh-pages
          user_name: ${{ env.GH_BOT_NAME }}
          user_email: ${{ env.GH_BOT_EMAIL }}

      # The step is only used to build docs while pushing to PR branch
      - name: Publish pull-request docs
        if: env.GH_EVENT_OPEN_PR_UPSTREAM == 'true'
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ${{ env.PUBLISH_DIR }}
          destination_dir: ./pull/${{ github.event.number }}
          allow_empty_commit : true
          keep_files: true
          commit_message: ${{ github.event.pull_request.title }}
          publish_branch: gh-pages
          user_name: ${{ env.GH_BOT_NAME }}
          user_email: ${{ env.GH_BOT_EMAIL }}

      # The step is only used to build docs while pushing to PR branch
      - name: Comment with URL to published pull-request docs
        if: env.GH_EVENT_OPEN_PR_UPSTREAM == 'true'
        env:
          PR_NUM: ${{ github.event.number }}
        uses: mshick/add-pr-comment@b8f338c590a895d50bcbfa6c5859251edc8952fc # v2.8.2
        with:
          message: |
            View rendered docs @ https://intelpython.github.io/dpnp/pull/${{ env.PR_NUM }}/index.html
          allow-repeats: false

  # The job is only used to build docs when PR is closed (action from PR branch)
  clean:
    if: |
      github.event_name == 'pull_request' && github.event.action == 'closed' &&
      github.event.pull_request && !github.event.pull_request.base.repo.fork

    needs: build-and-deploy

    permissions:
      # Needed to remove docs for closed pull request from the repo
      contents: write
      # Needed to modify a comment in the pull request's issue
      pull-requests: write

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          fetch-depth: 0

      - name: Remove docs [PR closed]
        env:
          PR_NUM: ${{ github.event.number }}
        run: |
          git remote add tokened_docs https://IntelPython:${{ secrets.GITHUB_TOKEN }}@github.com/IntelPython/dpnp.git
          git fetch tokened_docs
          git checkout --track tokened_docs/gh-pages
          echo `pwd`
          [ -d pull/${PR_NUM} ] && git rm -rf pull/${PR_NUM}
          git config --global user.name ${{ env.GH_BOT_NAME }}
          git config --global user.email ${{ env.GH_BOT_EMAIL }}
          git commit -m "Removing docs for closed pull request ${PR_NUM}"
          git push tokened_docs gh-pages

      - name: Modify the comment with URL to official documentation
        uses: mshick/add-pr-comment@b8f338c590a895d50bcbfa6c5859251edc8952fc # v2.8.2
        with:
          find: |
            View rendered docs @.+
          replace: |
            View rendered docs @ https://intelpython.github.io/dpnp/index.html