docs: add aggregated Javadoc generation via site-javadoc profile

Add a `site-javadoc` Maven profile that generates unified cross-module
Javadoc using maven-javadoc-plugin's aggregate goal. Cross-module @see
and {@link} references resolve as navigable HTML links.

- Add site-javadoc profile to parent POM with aggregate goal
- Move Javadoc menu entry from global menu to per-version menu in dev.yml
- Add placeholder docs/public/dev/apidocs/index.html for unreleased versions
- Update RELEASE.md with Javadoc generation steps for major/minor releases
- Add Javadoc aggregation verification step to CI release profile workflow

Author: kabir

.github/workflows/build-with-release-profile.yml

@@ -46,6 +46,9 @@ jobs:
           -Dgpg.skip=true
           -Drelease.auto.publish=false
 
+      - name: Verify aggregated Javadoc generation
+        run: mvn -B javadoc:aggregate -Psite-javadoc
+
       - name: Prepare PR info
         run: |
           mkdir -p pr_info

RELEASE.md

@@ -186,6 +186,24 @@ Update the previous default version's data file (e.g., `docs/data/versions/OLD_V
 
 Review the new version's content for accuracy — ensure all pages reflect features available in this release.
 
+#### Generate Javadoc (major/minor releases only)
+
+For major and minor releases (X.Y.0.Final), generate aggregated Javadoc. Skip this step for micro/patch releases (X.Y.Z.Final where Z > 0) — the API surface doesn't change meaningfully.
+
+```bash
+# Generate aggregated Javadoc (from the tagged commit)
+mvn javadoc:aggregate -Psite-javadoc
+
+# Copy to the release version directory (overwrites the placeholder)
+cp -r docs/public/dev/apidocs docs/public/X.Y.Z.Final/apidocs
+
+# Commit the generated Javadoc
+git add docs/public/X.Y.Z.Final/apidocs
+git commit -m "docs: add Javadoc for X.Y.Z.Final"
+```
+
+The Javadoc menu entry in the version's data file is inherited automatically from dev — no manual editing needed.
+
 ### 10. Increment to Next SNAPSHOT
 
 Prepare repository for next development cycle:

docs/data/menu.yml

@@ -7,11 +7,6 @@ items:
     path: "/announces"
     icon: "fa-regular fa-newspaper"
     position: "bottom"
-  - title: "Javadoc"
-    path: "https://javadoc.io/doc/org.a2aproject.sdk"
-    icon: "fa-solid fa-file-code"
-    target: "_blank"
-    position: "bottom"
   - title: "Community"
     path: "/community"
     icon: "fa-solid fa-users"

docs/data/versions/1.0.0.Final.yml

@@ -28,3 +28,7 @@ menu:
   - title: "Examples"
     path: "/examples"
     icon: "fa-solid fa-flask"
+  - title: "Javadoc"
+    path: "/apidocs/"
+    icon: "fa-solid fa-file-code"
+    target: "_blank"

docs/data/versions/1.1.0.Final.yml

@@ -31,3 +31,7 @@ menu:
   - title: "Examples"
     path: "/examples"
     icon: "fa-solid fa-flask"
+  - title: "Javadoc"
+    path: "/apidocs/"
+    icon: "fa-solid fa-file-code"
+    target: "_blank"

docs/data/versions/dev.yml

@@ -31,3 +31,7 @@ menu:
   - title: "Examples"
     path: "/examples"
     icon: "fa-solid fa-flask"
+  - title: "Javadoc"
+    path: "/apidocs/"
+    icon: "fa-solid fa-file-code"
+    target: "_blank"