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
    timeout-minutes: 20
    defaults:
      run:
        working-directory: github-pages

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Set up Node
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        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@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: github-pages/dist