mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Shahin Saadati
4505cb7e13
## Summary
The published Kotlin API reference has rendered **0.5.0** since it was
last
generated — four releases behind `main`, which is on 0.9.0. This
regenerates it
and fixes the generator that made it impossible.
It is not a forgotten manual step. `tools/kotlin-api-docs/generate.sh`
cannot
run against any adk-kotlin newer than **v0.6.0**.
## Why it was stuck
adk-kotlin moved from Dokka **1.9.20** to **2.2.0** at **v0.7.0**, and
Dokka 2
changed three things the script depends on:
1. **The task is gone.** `dokkaHtmlMultiModule` survives only as a
disabled
stub. Against a v0.9.0 clone, `./gradlew tasks --all` lists it verbatim
as:
```
dokkaHtmlMultiModule - [⚠ V1 tasks disabled] Runs all subprojects …
```
The build fails before generating anything.
2. **The output path moved** from `build/dokka/htmlMultiModule` to
`build/dokka/html`.
3. **Root aggregation is gone.** Dokka 1 inferred the unified
multi-module site
from the subprojects; Dokka 2 requires an explicit
`dependencies { dokka(project(...)) }` block, and adk-kotlin's root
build has
none. So even with the task name fixed there is no combined site to copy
—
only a dozen disconnected per-module ones.
## What this changes
**`tools/kotlin-api-docs/generate.sh`** — the three fixes above, plus a
post-generation check that `index.html` actually renders the requested
version.
Nothing verified that before, which is exactly how a 0.5.0 site sat in
the repo
looking freshly built.
The aggregation block is injected into the throwaway clone the script
already
makes, rather than sent upstream to adk-kotlin. That keeps the whole fix
inside
adk-docs — no second repo, no second review — and makes the module list
a docs
decision rather than an SDK one.
**`docs/api-reference/kotlin/`** — regenerated at 0.9.0. 2,462 files.
## Module coverage changes, and not purely additively
Please review this part specifically; it is the only judgement call
here.
| Module | Before | After | |
|---|---|---|---|
| `core`, `a2a`, `litertlm`, `processor`, `webserver` | ✅ | ✅ |
unchanged |
| `integrations` | ❌ | ✅ | **added** |
| `testing` | ❌ | ✅ | **added** |
| `examples` | ✅ | ❌ | **dropped** |
| `firebase`, `mlkit` | ❌ | ❌ | attempted, produce nothing |
- **`integrations` matters most.** It hosts
`BigQueryAgentAnalyticsPlugin`,
which `docs/integrations/bigquery-agent-analytics.md` documents and the
API
reference has never covered.
- **`examples` is dropped** because it is sample code rather than API
surface,
and it declares a JDK 21 toolchain that fails to auto-provision and
takes the
entire build down with it. Happy to restore it if you disagree, but it
needs
the toolchain problem solved first.
- **`firebase` and `mlkit` aggregate but emit empty directories** —
Dokka 2
generates no pages for their androidMain source sets. I left them out
rather
than shipping empty modules that imply coverage that is not there.
Making them
work needs a Dokka source-set fix in adk-kotlin, so it is out of scope
here.
## Verification
- A clean run of the committed script reproduces this exact tree.
- `index.html` renders `0.9.0`, and no file under
`docs/api-reference/kotlin/`
still contains `0.5.0`.
- The one deep link into the reference —
`docs/runtime/runconfig.md:364`, into
`google-adk-kotlin-core/com.google.adk.kt.agents/-run-config/` — still
resolves.
- The GA tag is injected exactly once per page. Eight files are skipped:
the
`navigation.html` fragments, which have no `<head>` to inject into.
- No temp-clone paths leaked into the generated HTML.
Built with **JDK 26** and Android SDK **platform 34**. adk-kotlin
declares a JDK
17 toolchain, but Dokka never needed to launch it for the aggregated
modules.
## Reviewing 2,462 files
Almost all of it is generated HTML. The only hand-written change is
`tools/kotlin-api-docs/generate.sh` (+57/-13); everything else is Dokka
output.
Reviewing the script and spot-checking a couple of rendered pages is the
useful
version of this review.
## Relationship to #2152
#2152 pins adk-docs to adk-kotlin 1.0.0 and lists regenerating this
reference on
its pre-merge checklist, blocked on a `v1.0.0` tag that does not exist
yet.
This PR deliberately does **not** wait for that. Doing it at 0.9.0 now
clears
four releases of staleness immediately and proves the toolchain works
while
there is no deadline, instead of discovering the generator is broken on
release
day. Once 1.0.0 ships, #2152 re-runs the same script with a different
argument.