Skip to content

docs: fix broken links and code examples; publish Java Javadoc in CI#152

Merged
zantvoort merged 1 commit into
mainfrom
docs/fix-broken-links-and-examples
Jul 1, 2026
Merged

docs: fix broken links and code examples; publish Java Javadoc in CI#152
zantvoort merged 1 commit into
mainfrom
docs/fix-broken-links-and-examples

Conversation

@zantvoort

Copy link
Copy Markdown
Collaborator

Summary

Fixes several broken links and incorrect code examples across the docs and landing page, plus a CI bug that leaves the Java Javadoc unpublished on orm.st. Documentation changes are applied to docs/ and the latest versioned_docs/version-1.11.5 snapshot only (older snapshots left frozen).

Changes

  • Landing page (src/pages/index.js) — the topCities generated-SQL panel now shows GROUP BY u.city_id instead of the expanded c.id, c.name, c.population, c.country. Verified against the framework: .groupBy(User_.city) on a single-column-PK @FK flattens to a single leaf and resolves to the foreign-key column on the driving table (same resolution as WHERE).
  • getting-started.md / index.md — replaced broken absolute links /dirty-checking and /ai with relative doc links (docs are served under /docs, so root-absolute links 404).
  • relationships.md — switched the many-to-one example to orm.get so it reads user.city.name. The previous orm.find + user?.city.name did not compile (safe-call chain on a nullable receiver).
  • configuration.md — added an explicit {#schema-validation} anchor to the storm.validation.schema_mode heading so the five "Schema Validation" cross-references (spring-integration, faq ×2, entities, migration-from-jpa) resolve.
  • faq.md — retargeted the deferred-loading link to refs.md#deferred-loading; entities.md#deferred-loading-with-ref did not exist.
  • .github/workflows/docs.yml — the "Copy Javadoc" step guarded on target/reports/apidocs (Maven 4), but mvn javadoc:aggregate on the Maven 3.9.x runner writes to target/site/apidocs, so the copy silently no-opped and an empty static/api/java shipped. Now copies from either path and fails loudly if neither exists.

Verification

  • Framework code + tests confirm the GROUP BY u.city_id behavior (testGroupByInlineRecord asserts the FK leaf resolves to city_id).
  • Link-checked docs/ and version-1.11.5 — all in-content links now resolve.
  • Probed the live site: /api/java/index.html returns 404, all five /api/kotlin/<module>/index.html return 200. The workflow fix addresses the Java 404 on the next docs deploy.

- landing page: topCities generated SQL groups by u.city_id (the FK column
  .groupBy(User_.city) actually emits), not the expanded city columns
- getting-started/index: replace broken absolute /dirty-checking and /ai
  links with relative doc links (docs now served under /docs)
- relationships: use orm.get so the example reads user.city.name (the old
  orm.find + user?.city.name did not compile)
- configuration: add {#schema-validation} anchor so the five
  "Schema Validation" cross-references resolve
- faq: point deferred-loading link at refs.md#deferred-loading
  (entities.md#deferred-loading-with-ref did not exist)
- docs.yml: copy aggregate Javadoc from target/site/apidocs (Maven 3) as
  well as target/reports/apidocs (Maven 4) and fail loudly if absent, so
  /api/java/index.html stops 404ing on orm.st

Doc fixes applied to docs/ and the latest versioned_docs snapshot only.
@zantvoort zantvoort merged commit 3c1447c into main Jul 1, 2026
7 checks passed
@zantvoort zantvoort deleted the docs/fix-broken-links-and-examples branch July 1, 2026 06:51
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