rtd.yml

name: 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@v7
        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@v7
        with:
          ref: ${{ needs.set_options.outputs.ref }}
          path: flopy

      - name: Checkout MODFLOW 6
        uses: actions/checkout@v7
        with:
          repository: MODFLOW-ORG/modflow6
          path: modflow6

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

      - name: Setup pixi
        uses: prefix-dev/setup-pixi@v0.10.0
        with:
          pixi-version: v0.70.1
          manifest-path: modflow6/pixi.toml

      - name: Install Python dependencies
        working-directory: modflow6
        run: |
          pixi run -e rtd install
          pixi run -e rtd pip install "../flopy[optional,test]"

      - name: Workaround OpenGL issue on Linux
        if: runner.os == 'Linux'
        working-directory: modflow6
        run: |
          # referenced from https://github.com/pyvista/pyvista/blob/main/.github/workflows/vtk-pre-test.yml#L53
          pixi run -e rtd pip uninstall vtk
          pixi run -e rtd 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 Modflow-related executables
        uses: modflowpy/install-modflow-action@v1

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

      - name: Setup GNU Fortran
        uses: fortran-lang/setup-fortran@v1
        with:
          compiler: gcc
          version: 13

      - name: Set up headless display
        uses: pyvista/setup-headless-display-action@v4

      - name: Build MODFLOW 6
        working-directory: modflow6
        run: |
          pixi run -e rtd meson setup builddir --buildtype=debugoptimized --prefix=$(pwd) --libdir=bin
          pixi run -e rtd meson install -C builddir
          pixi run -e rtd meson test --verbose --no-rebuild -C builddir
          echo "$(pwd)/bin" >> $GITHUB_PATH

      - name: Run tutorial and example notebooks
        working-directory: flopy/autotest
        run: pixi run --manifest-path=../../modflow6/pixi.toml -e rtd pytest -v -n auto test_example_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@v7
        with:
          name: notebooks-for-${{ needs.set_options.outputs.sha }}
          path: flopy/.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 }}