docs.yml

# Build the documentation and deploy to GitHub Pages using GitHub Actions.
#
# NOTE: Pin actions to a specific commit to avoid having the authentication
# token stolen if the Action is compromised. See the comments and links here:
# https://github.com/pypa/gh-action-pypi-publish/issues/27
#
name: documentation

# Only build PRs, the main branch, and releases. Pushes to branches will only
# be built when a PR is opened. This avoids duplicated buids in PRs comming
# from branches in the origin repository (1 for PR and 1 for push).
on:
  pull_request:
  push:
    branches:
      - main
  release:
    types:
      - published

# Use bash by default in all jobs
defaults:
  run:
    # The -l {0} is necessary for conda environments to be activated
    # But this breaks on MacOS if using actions/setup-python:
    # https://github.com/actions/setup-python/issues/132
    shell: bash -l {0}

jobs:
  #############################################################################
  # Build the docs
  build:
    runs-on: ubuntu-latest
    env:
      REQUIREMENTS: env/requirements-build.txt env/requirements-docs.txt
      PYTHON: "3.12"

    steps:

      # Checks-out your repository under $GITHUB_WORKSPACE
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # Need to fetch more than the last commit so that setuptools-scm can
          # create the correct version string. If the number of commits since
          # the last release is greater than this, the version still be wrong.
          # Increase if necessary.
          fetch-depth: 100
          # The GitHub token is preserved by default but this job doesn't need
          # to be able to push to GitHub.
          persist-credentials: false

      # Need the tags so that setuptools-scm can form a valid version number
      - name: Fetch git tags
        run: git fetch origin 'refs/tags/*:refs/tags/*'

      - name: Setup Miniconda
        uses: conda-incubator/setup-miniconda@v3
        with:
          python-version: ${{ env.PYTHON }}
          miniforge-variant: Mambaforge
          use-mamba: true
          channels: conda-forge,defaults
          # Allow mamba to use other than tar.bz2
          # (otherwise it cannot find latest versions that
          # don't use tar-bz2 files, see
          # https://github.com/conda-incubator/setup-miniconda/issues/267)
          use-only-tar-bz2: false

      - name: Collect requirements
        run: |
          echo "Install Dependente to capture dependencies:"
          mamba install dependente==0.3.0 -c conda-forge
          echo ""
          echo "Capturing run-time dependencies:"
          dependente --source install > requirements-full.txt
          echo "Capturing dependencies from:"
          for requirement in $REQUIREMENTS
          do
            echo "  $requirement"
            cat $requirement >> requirements-full.txt
          done
          echo ""
          echo "Collected dependencies:"
          cat requirements-full.txt

      - name: Rename conda-forge packages
        run: |
          echo "Rename conda-forge packages in requirements-full.txt"
          # Replace "build" for "python-build"
          sed -s --in-place 's/^build$/python-build/' requirements-full.txt
          echo "Renamed dependencies:"
          cat requirements-full.txt

      - name: Setup caching for conda packages
        uses: actions/cache@v4
        with:
          path: ~/conda_pkgs_dir
          key: conda-${{ runner.os }}-${{ env.PYTHON }}-${{ hashFiles('requirements-full.txt') }}

      - name: Install requirements
        run: mamba install --quiet --file requirements-full.txt python=$PYTHON

      - name: List installed packages
        run: mamba list

      - name: Build source and wheel distributions
        run: |
          make build
          echo ""
          echo "Generated files:"
          ls -lh dist/

      - name: Install the package
        run: python -m pip install --no-deps dist/*.whl

      - name: Build the documentation
        run: |
          # Install xvfb and run some commands to allow pyvista to run on
          # a headless system.
          sudo apt-get install xvfb
          export DISPLAY=:99.0
          export PYVISTA_OFF_SCREEN=true
          export PYVISTA_USE_IPYVTK=true
          Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
          sleep 3
          # Build the docs
          make -C doc clean all

      # Store the docs as a build artifact so we can deploy it later
      - name: Upload HTML documentation as an artifact
        # Only if not a pull request
        if: success() && github.event_name != 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: docs-${{ github.sha }}
          path: doc/_build/html

  #############################################################################
  # Publish the documentation to gh-pages
  publish:
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'release' || github.event_name == 'push'

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Fetch the built docs from the "build" job
      - name: Download HTML documentation artifact
        uses: actions/download-artifact@v4
        with:
          name: docs-${{ github.sha }}
          path: doc/_build/html

      - name: Checkout the gh-pages branch in a separate folder
        uses: actions/checkout@v4
        with:
          ref: gh-pages
          # Checkout to this folder instead of the current one
          path: deploy
          # Download the entire history
          fetch-depth: 0

      - name: Push the built HTML to gh-pages
        run: |
          # Detect if this is a release or from the main branch
          if [[ "${{ github.event_name }}" == "release" ]]; then
              # Get the tag name without the "refs/tags/" part
              version="${GITHUB_REF#refs/*/}"
          else
              version=dev
          fi
          echo "Deploying version: $version"
          # Make the new commit message. Needs to happen before cd into deploy
          # to get the right commit hash.
          message="Deploy $version from $(git rev-parse --short HEAD)"
          cd deploy
          # Need to have this file so that Github doesn't try to run Jekyll
          touch .nojekyll
          # Delete all the files and replace with our new  set
          echo -e "\nRemoving old files from previous builds of ${version}:"
          rm -rvf ${version}
          echo -e "\nCopying HTML files to ${version}:"
          cp -Rvf ../doc/_build/html/ ${version}/
          # If this is a new release, update the link from /latest to it
          if [[ "${version}" != "dev" ]]; then
              echo -e "\nSetup link from ${version} to 'latest'."
              rm -f latest
              ln -sf ${version} latest
          fi
          # Stage the commit
          git add -A .
          echo -e "\nChanges to be applied:"
          git status
          # Configure git to be the GitHub Actions account
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git config user.name "github-actions[bot]"
          # If this is a dev build and the last commit was from a dev build
          # (detect if "dev" was in the previous commit message), reuse the
          # same commit
          if [[ "${version}" == "dev" && `git log -1 --format='%s'` == *"dev"* ]]; then
              echo -e "\nAmending last commit:"
              git commit --amend --reset-author -m "$message"
          else
              echo -e "\nMaking a new commit:"
              git commit -m "$message"
          fi
          # Make the push quiet just in case there is anything that could leak
          # sensitive information.
          echo -e "\nPushing changes to gh-pages."
          git push -fq origin gh-pages 2>&1 >/dev/null
          echo -e "\nFinished uploading generated files."