docs.yml

name: Deploy Documentation

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

# GitHub's recommended settings for Pages deployments: serialize on the "pages"
# group and let an in-progress deployment finish (cancelling it mid-flight is
# what left the legacy branch build in a "Deployment failed, try again later"
# state that only cleared on a manual rerun).
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: temurin
          cache: maven

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
          cache-dependency-path: website/package-lock.json

      - name: Install website dependencies
        run: npm ci
        working-directory: website

      - name: Resolve released version
        id: version
        run: echo "value=$(node -p 'require("./website/versions.json")[0]')" >> "$GITHUB_OUTPUT"

      - name: Build project (skip tests)
        run: mvn install -DskipTests -q -Drevision=${{ steps.version.outputs.value }}

      - name: Generate Javadoc (aggregate)
        run: |
          # Publish only the public Java API:
          #   storm-foundation -> st.orm, st.orm.mapping (Entity, Ref, annotations)
          #   storm-java21     -> st.orm.repository, st.orm.template (ORMTemplate,
          #                       query builder, repositories)
          # Everything else is excluded on purpose:
          #   - Kotlin modules (Ktor, compiler-plugin variants) have no module
          #     descriptor and break aggregation ("named and unnamed modules");
          #     they are published separately as KDoc under /api/kotlin.
          #   - storm-core is the internal engine (st.orm.core.*).
          #   - dialect SPIs, storm-test and storm-metamodel-processor are not
          #     part of the user-facing API; Spring/Jackson are integrations.
          # Keep >= 2 named modules so javadoc stays in module mode and pages keep
          # their <module>/<package> paths (the docs link to storm.foundation/...).
          mvn javadoc:aggregate -q \
            -Drevision=${{ steps.version.outputs.value }} \
            -Dmaven.javadoc.failOnError=false \
            -DadditionalJOption=--enable-preview \
            -Ddoclint=none \
            -pl '!:storm-kotlin,!:storm-kotlin-spring,!:storm-kotlin-spring-boot-starter,!:storm-kotlinx-serialization,!:storm-metamodel-ksp,!:storm-spring-boot-starter,!:storm-jackson3,!:storm-ktor,!:storm-ktor-test,!:storm-ktor-koin,!:storm-compiler-plugin-2.0,!:storm-compiler-plugin-2.1,!:storm-compiler-plugin-2.2,!:storm-compiler-plugin-2.3,!:storm-compiler-plugin-2.4,!:storm-metamodel-processor,!:storm-core,!:storm-test,!:storm-jackson2,!:storm-oracle,!:storm-mssqlserver,!:storm-postgresql,!:storm-mysql,!:storm-mariadb,!:storm-sqlite,!:storm-h2,!:storm-spring'

      - name: Copy Javadoc to website/static/api/java
        run: |
          mkdir -p website/static/api/java
          # The aggregate report goal writes under the reporting output dir:
          # target/site/apidocs on Maven 3.x, target/reports/apidocs on Maven 4.x.
          copied=""
          # Require index.html specifically: a failed aggregate can still leave
          # an empty apidocs dir, and a plain -d check would treat that as success
          # and deploy an empty /api/java.
          for src in target/site/apidocs target/reports/apidocs; do
            if [ -f "$src/index.html" ]; then
              cp -r "$src"/* website/static/api/java/
              copied="$src"
              break
            fi
          done
          if [ -z "$copied" ]; then
            echo "::error::Aggregate Javadoc not found (checked target/site/apidocs and target/reports/apidocs); /api/java/index.html would 404"
            exit 1
          fi
          echo "Copied aggregate Javadoc from $copied"

      - name: Copy KDoc to website/static/api/kotlin
        run: |
          for module in storm-kotlin storm-kotlin-spring storm-kotlin-spring-boot-starter storm-metamodel-ksp storm-kotlinx-serialization; do
            if [ -d "$module/target/dokka" ]; then
              mkdir -p "website/static/api/kotlin/$module"
              cp -r "$module/target/dokka/"* "website/static/api/kotlin/$module/"
            fi
          done

      - name: Generate llms-full.txt
        run: bash scripts/generate-llms-full.sh
        working-directory: website

      - name: Build Docusaurus
        run: npm run build
        working-directory: website

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./website/build

  # Deploy the artifact with the official Pages action instead of pushing to a
  # gh-pages branch and relying on GitHub's flaky legacy branch builder.
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url || steps.deploy-retry.outputs.page_url }}
    steps:
      # GitHub Pages' backend intermittently fails during "syncing_files"
      # ("Deployment failed, try again later"), and a fresh deployment then
      # succeeds — which is why a manual rerun always worked. actions/deploy-pages
      # does not retry a failed deployment, so do it here: attempt once, wait,
      # and retry once before failing the job.
      - name: Deploy to GitHub Pages
        id: deploy
        continue-on-error: true
        uses: actions/deploy-pages@v4

      - name: Wait before retry
        if: steps.deploy.outcome == 'failure'
        run: sleep 45

      - name: Deploy to GitHub Pages (retry)
        id: deploy-retry
        if: steps.deploy.outcome == 'failure'
        uses: actions/deploy-pages@v4