Skip to content

Commit 636e37d

Browse files
authored
docs(site): enhance extras content and add search, sitemap, and diagr… (a2aproject#967)
docs(site): enhance extras content and add search, sitemap, and diagram plugins - Expand Android HTTP client docs with usage guide, auto-discovery, and feature list - Add Roq Lunr search plugin with overlay, button, and search index template - Add Roq sitemap and diagram plugins - Extract roq.version property to deduplicate hardcoded versions - Fix HTML entities in markdown (&lt; → <, &ge; → >=) - Fix search overlay z-index stacking and code copy button styling Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent 6e78304 commit 636e37d

9 files changed

Lines changed: 64 additions & 11 deletions

File tree

‎docs/content/extras/http-clients.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ layout: page
66

77
# HTTP Clients
88

9-
The A2A SDK uses an `A2AHttpClient` abstraction for all HTTP communication — fetching agent cards, making transport calls, and SSE streaming. By default, the SDK uses a JDK 11+ HttpClient implementation. These extras provide alternative implementations.
9+
The A2A SDK uses an `A2AHttpClient` abstraction for all HTTP communication — fetching agent cards, making transport calls, and Server-Sent Events (SSE) streaming. By default, the SDK uses a JDK 11+ HttpClient implementation. These extras provide alternative implementations.
1010

1111
## Vert.x HTTP Client
1212

@@ -177,11 +177,31 @@ mvn dependency:tree | grep vertx-web-client
177177

178178
## Android HTTP Client
179179

180-
HTTP client implementation for Android applications.
180+
181+
HTTP client implementation for Android applications, using `HttpURLConnection` under the hood — no external dependencies required.
182+
183+
### When to Use
184+
185+
- Android applications targeting API level 24+ (Android 7.0+)
186+
- Mobile apps that need to communicate with A2A agents
187+
188+
### 1. Add Dependency
181189

182190
```xml
183191
<dependency>
184192
<groupId>org.a2aproject.sdk</groupId>
185193
<artifactId>a2a-java-sdk-http-client-android</artifactId>
186194
</dependency>
187195
```
196+
197+
198+
### 2. Automatic Discovery (No Code Changes)
199+
200+
The `AndroidA2AHttpClientProvider` has **priority 110** and detects the Android runtime automatically. On non-Android runtimes, the provider returns priority `-1` and the SDK falls back to the next available client.
201+
202+
### Features
203+
204+
- **GET, POST, DELETE** requests with fluent builder API
205+
- **SSE streaming** via `getAsyncSSE()` and `postAsyncSSE()` — async operations run on a dedicated cached thread pool (`A2A-Android-Net`)
206+
- **Timeouts**: 15 s connection, 60 s read
207+
- **Response size limit**: 10 MB

‎docs/content/extras/opentelemetry.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,8 @@ Response (with trace headers)
6767

6868
### Context-Aware Async Executor
6969

70-
> **Note:** The `AsyncManagedExecutorProducer` is provided by the **Quarkus reference server** (`reference/common`), not the OpenTelemetry module. It is documented here because it enables context propagation (including trace context) across async boundaries.
70+
> **Note:** The `AsyncManagedExecutorProducer` is provided by the **Quarkus reference server** ([`reference/common`](https://github.com/a2aproject/a2a-java/blob/main/reference/common/src/main/java/org/a2aproject/sdk/server/common/quarkus/AsyncManagedExecutorProducer.java)), not the OpenTelemetry module. It is documented here because it enables context propagation (including trace context) across async boundaries.
71+
7172

7273
The reference server replaces the default `AsyncExecutorProducer` with `AsyncManagedExecutorProducer`:
7374

‎docs/content/extras/replicated-queue-manager.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ kafka-topics.sh --create --topic replicated-events \
143143
```
144144

145145
- Guarantees global event ordering
146-
- Suitable for development, testing, and low-throughput production (&lt;1000 events/sec)
146+
- Suitable for development, testing, and low-throughput production (<1000 events/sec)
147147
- Cannot parallelize consumption
148148

149149
#### Partition by Task ID (Recommended)
@@ -159,7 +159,7 @@ The `ReactiveMessagingReplicationStrategy` sends the `taskId` as the Kafka messa
159159
- **Per-task ordering guarantee**: all events for a single task go to the same partition
160160
- **Horizontal scalability**: different tasks can be processed in parallel across partitions
161161
- **Consumer parallelism**: multiple consumer instances can process different partitions concurrently
162-
- **Rule of thumb**: number of partitions &ge; number of A2A instances
162+
- **Rule of thumb**: number of partitions >= number of A2A instances
163163

164164
### Consumer Group Configuration
165165

‎docs/content/extras/storage.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ quarkus.hibernate-orm.database.generation=update
4141

4242
#### For WildFly/Jakarta EE Servers
4343

44+
> **Note:** On a Jakarta EE application server, the JPA dependencies are provided by the runtime. Mark them with `<scope>provided</scope>` in your POM to avoid packaging conflicts.
45+
4446
Create or update your `persistence.xml`:
4547

4648
```xml

‎docs/content/search-index.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{#include fm/search-index.json /}

‎docs/pom.xml‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
<properties>
1616
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
1717
<skipITs>true</skipITs>
18+
<roq.version>2.1.4</roq.version>
1819
</properties>
1920

2021
<dependencyManagement>
@@ -26,39 +27,44 @@
2627
<type>pom</type>
2728
<scope>import</scope>
2829
</dependency>
30+
<dependency>
31+
<groupId>org.mvnpm</groupId>
32+
<artifactId>resolve-from</artifactId>
33+
<version>5.0.0</version>
34+
</dependency>
2935
</dependencies>
3036
</dependencyManagement>
3137

3238
<dependencies>
3339
<dependency>
3440
<groupId>io.quarkiverse.roq</groupId>
3541
<artifactId>quarkus-roq</artifactId>
36-
<version>2.1.4</version>
42+
<version>${roq.version}</version>
3743
</dependency>
3844
<dependency>
3945
<groupId>io.quarkiverse.roq</groupId>
4046
<artifactId>quarkus-roq-plugin-tagging</artifactId>
41-
<version>2.1.4</version>
47+
<version>${roq.version}</version>
4248
</dependency>
4349
<dependency>
4450
<groupId>io.quarkiverse.roq</groupId>
4551
<artifactId>quarkus-roq-theme-default</artifactId>
46-
<version>2.1.4</version>
52+
<version>${roq.version}</version>
4753
</dependency>
4854
<dependency>
4955
<groupId>io.quarkiverse.roq</groupId>
5056
<artifactId>quarkus-roq-plugin-markdown</artifactId>
51-
<version>2.1.4</version>
57+
<version>${roq.version}</version>
5258
</dependency>
5359
<dependency>
5460
<groupId>io.quarkiverse.roq</groupId>
5561
<artifactId>quarkus-roq-plugin-sitemap</artifactId>
56-
<version>2.1.4</version>
62+
<version>${roq.version}</version>
5763
</dependency>
5864
<dependency>
5965
<groupId>io.quarkiverse.roq</groupId>
6066
<artifactId>quarkus-roq-plugin-diagram</artifactId>
61-
<version>2.1.4</version>
67+
<version>${roq.version}</version>
6268
</dependency>
6369
<dependency>
6470
<groupId>io.quarkus</groupId>
@@ -76,6 +82,11 @@
7682
<version>1.0.6</version>
7783
<scope>provided</scope>
7884
</dependency>
85+
<dependency>
86+
<groupId>io.quarkiverse.roq</groupId>
87+
<artifactId>quarkus-roq-plugin-lunr</artifactId>
88+
<version>${roq.version}</version>
89+
</dependency>
7990
<dependency>
8091
<groupId>io.quarkus</groupId>
8192
<artifactId>quarkus-junit</artifactId>

‎docs/src/main/resources/templates/partials/roq-default/head-scripts.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{@java.lang.String tag}
22

33
{#bundle /}
4+
{#search-script /}
45

56
{#if site.data.containsKey("analytics")}
67
{#ga4 tag=site.data.getJsonObject('analytics').getString("ga4", "") /}

‎docs/src/main/resources/templates/partials/roq-default/sidebar-menu.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22
{@java.util.List<io.vertx.core.json.JsonObject> menu}
33
{@java.lang.String menuTitle}
44

5+
{#search-overlay /}
56
<section class="menu">
7+
{#search-button /}
68
<h3 class="section-title menu-title">{menuTitle ?: 'MENU'}</h3>
79
<ul>
810
{#for item in menu}

‎docs/web/_custom.css‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,21 @@
8686
opacity: 0.9;
8787
}
8888

89+
/* The search overlay is inside .sidebar.main which is position:fixed on */
90+
/* desktop — fixed elements always form stacking contexts (z-index:auto). */
91+
/* Main content paints after the sidebar in DOM order and covers it. */
92+
/* Lift the sidebar above main content when search is active. */
93+
94+
@media (width >= 48rem) {
95+
.sidebar.main:has(.search-overlay.active) {
96+
z-index: 10000;
97+
}
98+
}
99+
100+
.hljs-copy-wrapper {
101+
transform: none;
102+
}
103+
89104
/* ── Content column width ─────────────────────────────────────────────────── */
90105

91106
.page-content .content-main {

0 commit comments

Comments
 (0)