From 76b7b7ad2783b1cd1183cc316df87e0612e48494 Mon Sep 17 00:00:00 2001 From: Leon van Zantvoort Date: Wed, 1 Jul 2026 23:24:08 +0200 Subject: [PATCH] ci: publish only the public Java API with the released version The Java Javadoc showed "0.0.0-SNAPSHOT" and an inconsistent module list (the internal engine, a single dialect SPI, the test-support module). - Stamp the released version (newest versions.json entry) via -Drevision on the build and aggregate, so the docs read e.g. "Storm Framework 1.11.6 API". - Aggregate only storm-foundation (st.orm, st.orm.mapping) and storm-java21 (st.orm.repository, st.orm.template) -- the public Java API -- excluding the internal core, dialect SPIs, test, metamodel-processor, and Spring/Jackson. - Point the docs "Browse the Javadoc" link at /api/java/storm.foundation/st/orm/package-summary.html. --- .github/workflows/docs.yml | 29 +++++++++++++------ docs/api-java.md | 2 +- .../versioned_docs/version-1.11.6/api-java.md | 2 +- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c37318dbf..2bad5d156 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -37,23 +37,34 @@ jobs: 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 + run: mvn install -DskipTests -q -Drevision=${{ steps.version.outputs.value }} - name: Generate Javadoc (aggregate) run: | - # The aggregate covers the Java API only. Kotlin modules (Ktor and the - # compiler-plugin variants) have no module descriptor; mixing these - # "unnamed" modules with the named Java modules makes javadoc:aggregate - # fail ("named and unnamed modules"), which — with failOnError=false — - # silently produced no output and left /api/java 404. Exclude them here - # (Kotlin APIs are documented separately via KDoc under /api/kotlin). - # NOTE: add any future storm-compiler-plugin- variant below. + # 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 / 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-compiler-plugin-2.0,!:storm-compiler-plugin-2.1,!:storm-compiler-plugin-2.2,!:storm-compiler-plugin-2.3,!:storm-compiler-plugin-2.4' + -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-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: | diff --git a/docs/api-java.md b/docs/api-java.md index e1b6828f2..29e7d12d1 100644 --- a/docs/api-java.md +++ b/docs/api-java.md @@ -94,4 +94,4 @@ See [Metamodel](metamodel.md) for setup and usage. The aggregated Javadoc covers all Java modules in the Storm framework: -[Browse the Javadoc](../api/java/index.html) +[Browse the Javadoc](../api/java/storm.foundation/st/orm/package-summary.html) diff --git a/website/versioned_docs/version-1.11.6/api-java.md b/website/versioned_docs/version-1.11.6/api-java.md index e1b6828f2..29e7d12d1 100644 --- a/website/versioned_docs/version-1.11.6/api-java.md +++ b/website/versioned_docs/version-1.11.6/api-java.md @@ -94,4 +94,4 @@ See [Metamodel](metamodel.md) for setup and usage. The aggregated Javadoc covers all Java modules in the Storm framework: -[Browse the Javadoc](../api/java/index.html) +[Browse the Javadoc](../api/java/storm.foundation/st/orm/package-summary.html)