generate-documentation.yml

name: Generate Documentation

on:
  workflow_call:
    inputs:
      git_ref:
        description: 'Git ref to checkout (branch, tag, or commit SHA)'
        required: true
        type: string

env:
  GIT_REF: ${{ inputs.git_ref }}

jobs:
  generate-documentation:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [22.x]

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ env.GIT_REF }}
          fetch-depth: 0

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - name: Setup npm version 10
        run: |
          npm i -g npm@10 --registry=https://registry.npmjs.org
      - name: Cache node modules
        id: cache-nodemodules
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          # caching node_modules
          path: |
            node_modules
            */*/node_modules
          key: ${{ runner.os }}-deps-${{ matrix.node-version }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-deps-${{ matrix.node-version }}-
      - name: Install Dependencies
        if: steps.cache-nodemodules.outputs.cache-hit != 'true'
        run: npm ci

      - run: npm run build

      - name: Generate Documentation
        run: npm run docgen

      - name: Upload documentation files as artifact
        id: docs-artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/
          retention-days: 10

  deploy-docs-pages:
    permissions:
      id-token: write  # Needed for OIDC authentication
      pages: write # this permission is needed for deploying into Github Pages
    environment:
      name: github-pages
      url: ${{ steps.docs-artifact.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: generate-documentation
    steps:
      - name: Deploy to Documentation to GitHub Pages
        id: docs-artifact
        uses: actions/deploy-pages@v4