docs: add aggregated Javadoc generation via site-javadoc profile

.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

.gitignore

@@ -48,6 +48,10 @@ nbproject/
 # TLS Certificates
 .certs/
 
+# Generated Javadoc (keep only the placeholder)
+docs/public/dev/apidocs/*
+!docs/public/dev/apidocs/index.html
+
 # Private Claude config
 .claude/settings.local.json
 .serena/

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 structure matches `dev.yml` — copy it into the new version's data file when creating version files.
+
 ### 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"

docs/public/1.0.0.Final/apidocs/element-list

@@ -0,0 +1,98 @@
+itk
+org.a2aproject.sdk
+org.a2aproject.sdk.bom.test
+org.a2aproject.sdk.client
+org.a2aproject.sdk.client.config
+org.a2aproject.sdk.client.http
+org.a2aproject.sdk.client.transport.grpc
+org.a2aproject.sdk.client.transport.jsonrpc
+org.a2aproject.sdk.client.transport.jsonrpc.sse
+org.a2aproject.sdk.client.transport.rest
+org.a2aproject.sdk.client.transport.rest.sse
+org.a2aproject.sdk.client.transport.spi
+org.a2aproject.sdk.client.transport.spi.interceptors
+org.a2aproject.sdk.client.transport.spi.interceptors.auth
+org.a2aproject.sdk.client.transport.spi.sse
+org.a2aproject.sdk.common
+org.a2aproject.sdk.compat03
+org.a2aproject.sdk.compat03.client
+org.a2aproject.sdk.compat03.client.config
+org.a2aproject.sdk.compat03.client.http
+org.a2aproject.sdk.compat03.client.transport.grpc
+org.a2aproject.sdk.compat03.client.transport.jsonrpc
+org.a2aproject.sdk.compat03.client.transport.jsonrpc.sse
+org.a2aproject.sdk.compat03.client.transport.rest
+org.a2aproject.sdk.compat03.client.transport.rest.sse
+org.a2aproject.sdk.compat03.client.transport.spi
+org.a2aproject.sdk.compat03.client.transport.spi.interceptors
+org.a2aproject.sdk.compat03.client.transport.spi.interceptors.auth
+org.a2aproject.sdk.compat03.common
+org.a2aproject.sdk.compat03.conversion
+org.a2aproject.sdk.compat03.conversion.mappers.config
+org.a2aproject.sdk.compat03.conversion.mappers.domain
+org.a2aproject.sdk.compat03.conversion.mappers.params
+org.a2aproject.sdk.compat03.conversion.mappers.result
+org.a2aproject.sdk.compat03.grpc
+org.a2aproject.sdk.compat03.grpc.utils
+org.a2aproject.sdk.compat03.json
+org.a2aproject.sdk.compat03.server.apps.quarkus
+org.a2aproject.sdk.compat03.server.grpc.quarkus
+org.a2aproject.sdk.compat03.server.rest.quarkus
+org.a2aproject.sdk.compat03.spec
+org.a2aproject.sdk.compat03.tck.server
+org.a2aproject.sdk.compat03.transport.grpc.context
+org.a2aproject.sdk.compat03.transport.grpc.handler
+org.a2aproject.sdk.compat03.transport.jsonrpc.context
+org.a2aproject.sdk.compat03.transport.jsonrpc.handler
+org.a2aproject.sdk.compat03.transport.rest.context
+org.a2aproject.sdk.compat03.transport.rest.handler
+org.a2aproject.sdk.compat03.util
+org.a2aproject.sdk.examples.cloud
+org.a2aproject.sdk.examples.helloworld
+org.a2aproject.sdk.extras.common.events
+org.a2aproject.sdk.extras.opentelemetry
+org.a2aproject.sdk.extras.opentelemetry.client
+org.a2aproject.sdk.extras.opentelemetry.client.propagation
+org.a2aproject.sdk.extras.opentelemetry.it
+org.a2aproject.sdk.extras.pushnotificationconfigstore.database.jpa
+org.a2aproject.sdk.extras.queuemanager.replicated.core
+org.a2aproject.sdk.extras.queuemanager.replicated.mp_reactive
+org.a2aproject.sdk.extras.queuemanager.replicated.tests.multiinstance.app1
+org.a2aproject.sdk.extras.queuemanager.replicated.tests.multiinstance.app2
+org.a2aproject.sdk.extras.queuemanager.replicated.tests.multiinstance.common
+org.a2aproject.sdk.extras.taskstore.database.jpa
+org.a2aproject.sdk.grpc
+org.a2aproject.sdk.grpc.mapper
+org.a2aproject.sdk.grpc.utils
+org.a2aproject.sdk.integrations.microprofile
+org.a2aproject.sdk.itk
+org.a2aproject.sdk.jsonrpc.common.json
+org.a2aproject.sdk.jsonrpc.common.wrappers
+org.a2aproject.sdk.server
+org.a2aproject.sdk.server.agentexecution
+org.a2aproject.sdk.server.apps.quarkus
+org.a2aproject.sdk.server.auth
+org.a2aproject.sdk.server.common.quarkus
+org.a2aproject.sdk.server.config
+org.a2aproject.sdk.server.events
+org.a2aproject.sdk.server.extensions
+org.a2aproject.sdk.server.grpc.quarkus
+org.a2aproject.sdk.server.multiversion.jsonrpc
+org.a2aproject.sdk.server.multiversion.rest
+org.a2aproject.sdk.server.requesthandlers
+org.a2aproject.sdk.server.rest.quarkus
+org.a2aproject.sdk.server.tasks
+org.a2aproject.sdk.server.util
+org.a2aproject.sdk.server.util.async
+org.a2aproject.sdk.server.util.sse
+org.a2aproject.sdk.server.version
+org.a2aproject.sdk.spec
+org.a2aproject.sdk.sut
+org.a2aproject.sdk.testutils.docker
+org.a2aproject.sdk.transport.grpc.context
+org.a2aproject.sdk.transport.grpc.handler
+org.a2aproject.sdk.transport.jsonrpc.context
+org.a2aproject.sdk.transport.jsonrpc.handler
+org.a2aproject.sdk.transport.rest.context
+org.a2aproject.sdk.transport.rest.handler
+org.a2aproject.sdk.util

docs/public/1.0.0.Final/apidocs/help-doc.html

@@ -0,0 +1,202 @@
+<!DOCTYPE HTML>
+<html lang>
+<head>
+<!-- Generated by javadoc (17) on Tue Jul 21 16:04:42 BST 2026 -->
+<title>API Help (Java SDK A2A Parent 1.0.0.Final API)</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta name="dc.created" content="2026-07-21">
+<meta name="description" content="help">
+<meta name="generator" content="javadoc/HelpWriter">
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
+<link rel="stylesheet" type="text/css" href="script-dir/jquery-ui.min.css" title="Style">
+<link rel="stylesheet" type="text/css" href="jquery-ui.overrides.css" title="Style">
+<script type="text/javascript" src="script.js"></script>
+<script type="text/javascript" src="script-dir/jquery-3.7.1.min.js"></script>
+<script type="text/javascript" src="script-dir/jquery-ui.min.js"></script>
+</head>
+<body class="help-page">
+<script type="text/javascript">var pathtoroot = "./";
+loadScripts(document, 'script');</script>
+<noscript>
+<div>JavaScript is disabled on your browser.</div>
+</noscript>
+<div class="flex-box">
+<header role="banner" class="flex-header">
+<nav role="navigation">
+<!-- ========= START OF TOP NAVBAR ======= -->
+<div class="top-nav" id="navbar-top">
+<div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links</a></div>
+<ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
+<li><a href="index.html">Overview</a></li>
+<li>Package</li>
+<li>Class</li>
+<li>Use</li>
+<li><a href="overview-tree.html">Tree</a></li>
+<li><a href="deprecated-list.html">Deprecated</a></li>
+<li><a href="index-all.html">Index</a></li>
+<li class="nav-bar-cell1-rev">Help</li>
+</ul>
+</div>
+<div class="sub-nav">
+<div>
+<ul class="sub-nav-list">
+<li>Help:&nbsp;</li>
+<li><a href="#help-navigation">Navigation</a>&nbsp;|&nbsp;</li>
+<li><a href="#help-pages">Pages</a></li>
+</ul>
+</div>
+<div class="nav-list-search"><label for="search-input">SEARCH:</label>
+<input type="text" id="search-input" value="search" disabled="disabled">
+<input type="reset" id="reset-button" value="reset" disabled="disabled">
+</div>
+</div>
+<!-- ========= END OF TOP NAVBAR ========= -->
+<span class="skip-nav" id="skip-navbar-top"></span></nav>
+</header>
+<div class="flex-content">
+<main role="main">
+<h1 class="title">JavaDoc Help</h1>
+<ul class="help-toc">
+<li><a href="#help-navigation">Navigation</a>: 
+<ul class="help-subtoc">
+<li><a href="#help-search">Search</a></li>
+</ul>
+</li>
+<li><a href="#help-pages">Kinds of Pages</a>: 
+<ul class="help-subtoc">
+<li><a href="#overview">Overview</a></li>
+<li><a href="#package">Package</a></li>
+<li><a href="#class">Class or Interface</a></li>
+<li><a href="#doc-file">Other Files</a></li>
+<li><a href="#use">Use</a></li>
+<li><a href="#tree">Tree (Class Hierarchy)</a></li>
+<li><a href="#deprecated">Deprecated API</a></li>
+<li><a href="#constant-values">Constant Field Values</a></li>
+<li><a href="#serialized-form">Serialized Form</a></li>
+<li><a href="#all-packages">All Packages</a></li>
+<li><a href="#all-classes">All Classes and Interfaces</a></li>
+<li><a href="#index">Index</a></li>
+</ul>
+</li>
+</ul>
+<hr>
+<div class="sub-title">
+<h2 id="help-navigation">Navigation</h2>
+Starting from the <a href="index.html">Overview</a> page, you can browse the documentation using the links in each page, and in the navigation bar at the top of each page. The <a href="index-all.html">Index</a> and Search box allow you to navigate to specific declarations and summary pages, including: <a href="allpackages-index.html">All Packages</a>, <a href="allclasses-index.html">All Classes and Interfaces</a>
+<section class="help-section" id="help-search">
+<h3>Search</h3>
+<p>You can search for definitions of modules, packages, types, fields, methods, system properties and other terms defined in the API, using some or all of the name, optionally using "camelCase" abbreviations. For example:</p>
+<ul class="help-section-list">
+<li><code>j.l.obj</code> will match "java.lang.Object"</li>
+<li><code>InpStr</code> will match "java.io.InputStream"</li>
+<li><code>HM.cK</code> will match "java.util.HashMap.containsKey(Object)"</li>
+</ul>
+<p>Refer to the <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/javadoc/javadoc-search-spec.html">Javadoc Search Specification</a> for a full description of search features.</p>
+</section>
+</div>
+<hr>
+<div class="sub-title">
+<h2 id="help-pages">Kinds of Pages</h2>
+The following sections describe the different kinds of pages in this collection.
+<section class="help-section" id="overview">
+<h3>Overview</h3>
+<p>The <a href="index.html">Overview</a> page is the front page of this API document and provides a list of all packages with a summary for each.  This page can also contain an overall description of the set of packages.</p>
+</section>
+<section class="help-section" id="package">
+<h3>Package</h3>
+<p>Each package has a page that contains a list of its classes and interfaces, with a summary for each. These pages may contain the following categories:</p>
+<ul class="help-section-list">
+<li>Interfaces</li>
+<li>Classes</li>
+<li>Enum Classes</li>
+<li>Exceptions</li>
+<li>Errors</li>
+<li>Annotation Interfaces</li>
+</ul>
+</section>
+<section class="help-section" id="class">
+<h3>Class or Interface</h3>
+<p>Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a declaration and description, member summary tables, and detailed member descriptions. Entries in each of these sections are omitted if they are empty or not applicable.</p>
+<ul class="help-section-list">
+<li>Class Inheritance Diagram</li>
+<li>Direct Subclasses</li>
+<li>All Known Subinterfaces</li>
+<li>All Known Implementing Classes</li>
+<li>Class or Interface Declaration</li>
+<li>Class or Interface Description</li>
+</ul>
+<br>
+<ul class="help-section-list">
+<li>Nested Class Summary</li>
+<li>Enum Constant Summary</li>
+<li>Field Summary</li>
+<li>Property Summary</li>
+<li>Constructor Summary</li>
+<li>Method Summary</li>
+<li>Required Element Summary</li>
+<li>Optional Element Summary</li>
+</ul>
+<br>
+<ul class="help-section-list">
+<li>Enum Constant Details</li>
+<li>Field Details</li>
+<li>Property Details</li>
+<li>Constructor Details</li>
+<li>Method Details</li>
+<li>Element Details</li>
+</ul>
+<p><span class="help-note">Note:</span> Annotation interfaces have required and optional elements, but not methods. Only enum classes have enum constants. The components of a record class are displayed as part of the declaration of the record class. Properties are a feature of JavaFX.</p>
+<p>The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.</p>
+</section>
+<section class="help-section" id="doc-file">
+<h3>Other Files</h3>
+<p>Packages and modules may contain pages with additional information related to the declarations nearby.</p>
+</section>
+<section class="help-section" id="use">
+<h3>Use</h3>
+<p>Each documented package, class and interface has its own Use page.  This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A.  You can access this page by first going to the package, class or interface, then clicking on the USE link in the navigation bar.</p>
+</section>
+<section class="help-section" id="tree">
+<h3>Tree (Class Hierarchy)</h3>
+<p>There is a <a href="overview-tree.html">Class Hierarchy</a> page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. Classes are organized by inheritance structure starting with <code>java.lang.Object</code>. Interfaces do not inherit from <code>java.lang.Object</code>.</p>
+<ul class="help-section-list">
+<li>When viewing the Overview page, clicking on TREE displays the hierarchy for all packages.</li>
+<li>When viewing a particular package, class or interface page, clicking on TREE displays the hierarchy for only that package.</li>
+</ul>
+</section>
+<section class="help-section" id="deprecated">
+<h3>Deprecated API</h3>
+<p>The <a href="deprecated-list.html">Deprecated API</a> page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to shortcomings, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.</p>
+</section>
+<section class="help-section" id="constant-values">
+<h3>Constant Field Values</h3>
+<p>The <a href="constant-values.html">Constant Field Values</a> page lists the static final fields and their values.</p>
+</section>
+<section class="help-section" id="serialized-form">
+<h3>Serialized Form</h3>
+<p>Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to those who implement rather than use the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See Also" section of the class description.</p>
+</section>
+<section class="help-section" id="all-packages">
+<h3>All Packages</h3>
+<p>The <a href="allpackages-index.html">All Packages</a> page contains an alphabetic index of all packages contained in the documentation.</p>
+</section>
+<section class="help-section" id="all-classes">
+<h3>All Classes and Interfaces</h3>
+<p>The <a href="allclasses-index.html">All Classes and Interfaces</a> page contains an alphabetic index of all classes and interfaces contained in the documentation, including annotation interfaces, enum classes, and record classes.</p>
+</section>
+<section class="help-section" id="index">
+<h3>Index</h3>
+<p>The <a href="index-all.html">Index</a> contains an alphabetic index of all classes, interfaces, constructors, methods, and fields in the documentation, as well as summary pages such as <a href="allpackages-index.html">All Packages</a>, <a href="allclasses-index.html">All Classes and Interfaces</a>.</p>
+</section>
+</div>
+<hr>
+<span class="help-footnote">This help file applies to API documentation generated by the standard doclet.</span></main>
+<footer role="contentinfo">
+<hr>
+<p class="legal-copy"><small>Copyright &#169; 2026. All rights reserved.</small></p>
+</footer>
+</div>
+</div>
+</body>
+</html>