documentation.yml

name: Documentation

# Regenerate docs/html/ from the function help texts and commit the result.
#
# docs/html/ is generated output that is nevertheless tracked, so it drifts as soon
# as anyone edits a docstring or adds/removes a function without remembering to
# run updateDocumentation. Running it here instead means nobody has to.
#
# This deliberately does not gate pull requests: a docstring edit would then
# fail CI until the contributor installed MATLAB and regenerated by hand. The
# push job is the single writer, and it runs after the merge.
#
# Commits made with GITHUB_TOKEN do not trigger workflows, so this cannot loop.
# The commit message still carries [skip ci] regardless, since a doc-only
# commit would otherwise needlessly re-trigger this repo's other push-based
# workflows (e.g. Function tests), which key off the push event itself rather
# than the path filter this workflow uses.

on:
  push:
    branches: [develop, main]
    paths:
      - '**.m'
      - '.github/workflows/documentation.yml'
  workflow_dispatch:

permissions:
  contents: write

concurrency:
  # One writer per branch; a newer push supersedes an in-flight regeneration.
  group: documentation-${{ github.ref }}
  cancel-in-progress: true

jobs:
  update-documentation:
    name: Regenerate docs/html/
    runs-on: ubuntu-latest
    timeout-minutes: 20

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

      - name: Set up MATLAB
        uses: matlab-actions/setup-matlab@v3
        with:
          release: R2024b

      - name: Regenerate HTML documentation
        uses: matlab-actions/run-command@v3
        env:
          MLM_LICENSE_TOKEN: ${{ secrets.MATLAB_BATCH_TOKEN }}
        with:
          # genpath skips private/ and @class directories, so m2html's own
          # helpers (one of which is named strtok) never shadow a builtin.
          #
          # updateDocumentation rebuilds whichever tree findRAVENroot resolves
          # to, and findRAVENroot prefers a stored RAVEN.ravenPath preference
          # over the copy actually running. A runner has no such preference, but
          # clearing it and then asserting makes that a checked fact rather than
          # an assumption: regenerating a different checkout would otherwise
          # commit its documentation over this one's.
          command: |
            addpath(genpath(pwd));
            if ispref('RAVEN','ravenPath'); rmpref('RAVEN','ravenPath'); end
            root = findRAVENroot();
            assert(strcmp(root, pwd), ...
                'findRAVENroot resolved to %s, not the checkout at %s', root, pwd);
            updateDocumentation();

      - name: Commit regenerated documentation
        run: |
          # updateDocumentation deletes and rebuilds docs/html/, so stage first:
          # a plain "git diff" would not see added or removed pages.
          git add -A docs/html
          if git diff --cached --quiet -- docs/html; then
            echo "docs/html/ is already up to date."
            exit 0
          fi
          git config user.name  "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git commit -m "doc: regenerate HTML documentation for ${GITHUB_SHA:0:7} [skip ci]"
          git push