Skip to content

ci: fix Java Javadoc aggregate so /api/java deploys#159

Merged
zantvoort merged 1 commit into
mainfrom
ci/fix-java-javadoc-aggregate
Jul 1, 2026
Merged

ci: fix Java Javadoc aggregate so /api/java deploys#159
zantvoort merged 1 commit into
mainfrom
ci/fix-java-javadoc-aggregate

Conversation

@zantvoort

Copy link
Copy Markdown
Collaborator

Problem

https://orm.st/api/java/index.html (and the whole /api/java/ tree) 404s — the Javadoc is never published, while /api/kotlin/* works.

Root cause

The "Generate Javadoc (aggregate)" step in docs.yml fails:

[ERROR] Creating an aggregated report for both named and unnamed modules is not possible.
[ERROR] Fix the following projects:
 - storm-compiler-plugin-2.0 … 2.4, storm-ktor, storm-ktor-test

The aggregate pulls in Kotlin modules (Ktor + the compiler-plugin variants) that have no module descriptor. javadoc:aggregate can't mix these unnamed modules with the named Java modules. Because -Dmaven.javadoc.failOnError=false is set, the step still reports success while producing no output, so the copy step deploys an empty /api/java. (Confirmed: gh-pages has no api/java directory.)

Fix

  1. Exclude the non-Java modules from the aggregate -pl list: storm-ktor, storm-ktor-test, and storm-compiler-plugin-2.0…2.4. Every remaining source module has a module-info.java (all named), so aggregation succeeds. These Kotlin APIs are already published as KDoc under /api/kotlin.
  2. Harden the copy guard to require index.html (not just the directory), so a future empty/failed aggregate fails the build loudly instead of silently shipping an empty /api/java.

Verification

Verified every remaining module is named (find -name module-info.java). Running a local mvn install + javadoc:aggregate with the new exclusions to confirm index.html is produced. Once merged, the push to main triggers the docs deploy; with the hardened guard, if anything is still off it will fail rather than silently 404.

The aggregate report pulled in Kotlin modules (Ktor and the
compiler-plugin variants) that have no module descriptor. Mixing these
unnamed modules with the named Java modules makes javadoc:aggregate fail
with "named and unnamed modules"; because failOnError=false is set, the
step reported success while producing no output, leaving
https://orm.st/api/java a 404.

- Exclude the Kotlin / non-module-path modules from the aggregate (they
  are documented separately as KDoc under /api/kotlin).
- Require index.html in the copy step, so an empty aggregate fails the
  build loudly instead of silently deploying an empty /api/java.
@zantvoort

Copy link
Copy Markdown
Collaborator Author

✅ Validated locally: with the new exclusions, mvn install + mvn javadoc:aggregate exits 0 with no "named and unnamed modules" error and produces target/reports/apidocs/index.html (14 st.orm packages, 33 entries). The copy step finds it at target/reports/apidocs and the hardened index.html guard passes.

@zantvoort zantvoort merged commit 5910577 into main Jul 1, 2026
7 checks passed
@zantvoort zantvoort deleted the ci/fix-java-javadoc-aggregate branch July 1, 2026 20:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant