docs-publish.yml

# This workflow will publish API docs to GitHub Pages when a new release tag is added to the main branch

name: Publish API docs to GitHub Pages

on:
  release:
    types:
      - published
  workflow_dispatch:

jobs:
  check-tag:
    runs-on: ubuntu-latest
    steps:
      - name: Fetch the latest release tag
        id: fetch_latest_release_tag
        run: |
          LATEST_TAG=$(curl -s https://api.github.com/repos/${{ github.repository }}/releases/latest | jq -r '.tag_name')
          echo "LATEST_TAG=$LATEST_TAG" >> "$GITHUB_OUTPUT"
          echo "The latest release tag is $LATEST_TAG"

      - name: Check release tag on release event
        if: ${{ github.event_name == 'release' }}
        env:
          RELEASE_TAG: ${{ github.event.release.tag_name }}
          LATEST_TAG: ${{ steps.fetch_latest_release_tag.outputs.LATEST_TAG }}
        run: |
          if [[ "$RELEASE_TAG" != "$LATEST_TAG" ]]; then
            echo "Release tag $RELEASE_TAG does not match the latest tag $LATEST_TAG."
            exit 1
          else
            echo "Release tag $RELEASE_TAG matches the latest tag $LATEST_TAG."
          fi

  build:
    needs: check-tag
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repository
        uses: actions/checkout@v4
        with:
          ref: ${{ steps.fetch_latest_release_tag.outputs.LATEST_TAG }}

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install
        run: npm ci

      - name: Build docs
        run: npm run docs

      - name: Upload static files as artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/

  deploy:
    needs: build

    concurrency:
      group: docs-publish
      cancel-in-progress: true

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4