rtd.yml

name: FloPy documentation
on:
  push:
  pull_request:
    branches:
      - master
      - develop
  workflow_dispatch:
    inputs:
      ref:
        description: 'The tag, branch or commit hash to trigger an RTD build for. Branches and tags must be fully formed, e.g. refs/heads/<branch> or refs/tags/<tag> respectively.'
        required: false
        type: string
        default: 'refs/heads/develop'
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
  cancel-in-progress: true
jobs:
  set_options:
    name: Set options
    runs-on: ubuntu-22.04
    outputs:
      ref: ${{ steps.set_ref.outputs.ref }}
      sha: ${{ steps.set_sha.outputs.sha }}
    steps:
      
      - name: Set ref
        id: set_ref
        run: |
          # if ref was provided explicitly via workflow_dispatch, use it
          if [[ ("${{ github.event_name }}" == "workflow_dispatch") && (-n "${{ inputs.ref }}") ]]; then
            ref="${{ inputs.ref }}"
            echo "using ref $ref from workflow_dispatch"
          else
            # otherwise use the current branch
            ref="${{ github.ref }}"
            echo "using current ref $ref"
          fi
          echo "ref=$ref" >> $GITHUB_OUTPUT

      - name: Checkout flopy repo
        uses: actions/checkout@v4
        with:
          ref: ${{ steps.set_ref.outputs.ref }}

      - name: Set sha
        id: set_sha
        run: |
          if [[ ("${{ github.event_name }}" == "workflow_dispatch") && (-n "${{ inputs.ref }}") ]]; then
            sha=$(git rev-parse ${{ steps.set_ref.outputs.ref }})
          else
            sha="${{ github.sha }}"
          fi
          echo "sha=$sha" >> $GITHUB_OUTPUT

  rtd_build:
    name: Prepare and test notebooks
    needs: set_options
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ ubuntu-latest, macos-latest, windows-latest ]

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

    steps:
      - name: Checkout flopy repo
        uses: actions/checkout@v4
        with:
          ref: ${{ needs.set_options.outputs.ref }}

      - name: Output repo information
        run: |
          echo $GITHUB_REPOSITORY_OWNER
          echo $GITHUB_REPOSITORY
          echo $GITHUB_REF
          echo $GITHUB_EVENT_NAME

      - name: Setup Micromamba
        uses: mamba-org/setup-micromamba@v1
        with:
          environment-file: etc/environment.yml
          cache-environment: true
          cache-downloads: true
          create-args: >-
            python=3.12
          init-shell: >-
            bash
            powershell

      - name: Install Python dependencies
        run: |
          pip install --upgrade pip
          pip install .
      
      - name: Workaround OpenGL issue on Linux
        if: runner.os == 'Linux'
        run: |
          # referenced from https://github.com/pyvista/pyvista/blob/main/.github/workflows/vtk-pre-test.yml#L53
          pip uninstall -y vtk
          pip install --extra-index-url https://wheels.vtk.org trame vtk-osmesa
      
      - name: Install fonts on Linux
        if: runner.os == 'Linux'
        run: |
          echo ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true | sudo debconf-set-selections
          sudo apt-get install ttf-mscorefonts-installer fonts-liberation
          sudo rm -rf ~/.cache/matplotlib
      
      - name: Install OpenGL on Windows
        if: runner.os == 'Windows'
        shell: pwsh
        run: |
          Set-StrictMode -Version Latest
          $ErrorActionPreference = "Stop"
          $PSDefaultParameterValues['*:ErrorAction']='Stop'
          powershell .github/install_opengl.ps1

      - name: Install Modflow-related executables
        uses: modflowpy/install-modflow-action@v1

      - name: Install Modflow dev build executables
        uses: modflowpy/install-modflow-action@v1
        with:
          repo: modflow6-nightly-build

      - name: Install triangle (macOS workaround)
        if: runner.os == 'macOS'
        uses: modflowpy/install-modflow-action@v1
        with:
          repo: executables
          ostag: mac
          subset: triangle

      - name: Run tutorial and example notebooks
        working-directory: autotest
        run: pytest -v -n auto test_notebooks.py

      - name: Upload notebooks artifact for ReadtheDocs
        if: |
          github.repository_owner == 'modflowpy' && 
          runner.os == 'Linux' &&
          (
            github.event_name == 'push' ||
            github.event_name == 'workflow_dispatch'
          )
        uses: actions/upload-artifact@v4
        with:
          name: notebooks-for-${{ needs.set_options.outputs.sha }}
          path: .docs/Notebooks/*.ipynb

  # trigger rtd if previous job was successful
  rtd:
    name: Read the Docs trigger
    needs: 
      - rtd_build
      - set_options
    runs-on: ubuntu-latest
    if:
      github.repository_owner == 'modflowpy' &&
      (
          github.event_name == 'push' ||
          github.event_name == 'workflow_dispatch'
      )
    steps:
      - name: Trigger RTDs build
        uses: dfm/rtds-action@v1
        with:
          webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}
          webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}
          commit_ref: ${{ needs.set_options.outputs.ref }}