name: _Build documentation

on:
  workflow_call:
    inputs:
      run_tests:
        description: Run the documentation test suite before building
        required: false
        default: true
        type: boolean
      upload_pages_artifact:
        description: Upload the build for a later GitHub Pages deployment job
        required: false
        default: false
        type: boolean

permissions:
  contents: read

jobs:
  build:
    name: Build documentation
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: github-pages

    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
        with:
          persist-credentials: false

      - name: Set up Node
        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
        with:
          node-version: '22.22.3'
          cache: npm
          cache-dependency-path: github-pages/package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        if: inputs.run_tests
        run: npm test

      - name: Build documentation
        run: npm run build

      - name: Configure Pages
        if: inputs.upload_pages_artifact
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6

      - name: Upload Pages artifact
        if: inputs.upload_pages_artifact
        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
        with:
          path: github-pages/dist