make_docs.yaml

name: Documentation

on:
  push:
    branches:
      - main
      - develop
    tags:
      - '*'
  pull_request:

concurrency:
  # Skip intermediate builds: always.
  # Cancel intermediate builds: only if it is a pull request build.
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

jobs:
  docs:
    name: Documentation
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      statuses: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Julia
        uses: julia-actions/setup-julia@v2
        with:
          version: '1.11'

      - name: Restore Julia cache (packages, artifacts, compiled, registries)
        uses: actions/cache@v4
        with:
          path: |
            ~/.julia/packages
            ~/.julia/artifacts
            ~/.julia/compiled
            ~/.julia/registries
          # include Manifest.toml so cache invalidates when resolved versions change
          key: ${{ runner.os }}-julia-${{ hashFiles('**/Project.toml','**/Manifest.toml') }}
          restore-keys: |
           ${{ runner.os }}-julia-${{ hashFiles('**/Project.toml','**/Manifest.toml') }}

      - name: Prepare docs environment (develop local package, then instantiate)
        run: julia --project=docs -e 'using Pkg; Pkg.activate("docs"); Pkg.develop(PackageSpec(path=".")); Pkg.instantiate(update_registry=false)'

      - name: Build and deploy documentation
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: julia --project=docs docs/make.jl