eamxx-gh-pages.yml

# This workflow aims to automatically rebuild eamxx documentation
# every time the master branch is updated on github and within every PR

name: EAMxx Docs

on:
  # Runs every time master branch is updated
  push:
    branches: [ master ]
    # Only if docs-related files are touched
    paths:
      - components/eamxx/mkdocs.yml
      - components/eamxx/docs/**
      - components/eamxx/cime_config/namelist_defaults_scream.xml
  # Runs every time a PR is open against master
  pull_request:
    branches: [ master ]
    # Only if docs-related files are touched
    paths:
      - components/eamxx/mkdocs.yml
      - components/eamxx/docs/**
      - components/eamxx/cime_config/namelist_defaults_scream.xml

  label:
    types:
      - created

  workflow_dispatch:

concurrency:
  # Prevent 2+ copies of this workflow from running concurrently
  group: eamxx-docs-action

jobs:

  eamxx-docs:
    if: ${{ github.event.repository.name == 'scream' }}
    runs-on: ubuntu-latest

    steps:
      - name: Check out the repository
        uses: actions/checkout@v4
        with:
          persist-credentials: false
          show-progress: false
          # TODO: git rid of dependency on CIME
          # TODO: another option to investigate is a sparse checkout. 
          # In the scream repo, all other components do not need to be checked out. 
          # And even in the upstream, we mainly need only components/xyz/docs (and a few more places).
          submodules: true
  
      - name: Show action trigger
        run: |
          echo "= The job was automatically triggered by a ${{github.event_name}} event."

      - name: Set up Python 3.10
        uses: actions/setup-python@v5.1.0
        with:
          python-version: "3.10"

      - name: Install Python deps
        run: |
          pip install mkdocs pymdown-extensions mkdocs-material mdutils
  
      - name: Generate EAMxx params docs
        working-directory: components/eamxx/scripts
        run: |
          ./eamxx-params-docs-autogen

      - name: Build docs
        working-directory: components/eamxx
        run: |
          mkdocs build --strict --verbose

      # only deploy to the main github page when there is a push to master
      - if: ${{ github.event_name == 'push' }}
        name: GitHub Pages action
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          # Do not remove existing pr-preview pages
          clean-exclude: pr-preview
          folder: ./components/eamxx/site

      # If it's a PR from within the same repo, deploy to a preview page
      - if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
        name: Preview docs
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: components/eamxx/site/