Fix the Kotlin API reference generator for Dokka 2 and regenerate at 0.9.0 - #2204
Open
happyhuman wants to merge 1 commit into
Open
Fix the Kotlin API reference generator for Dokka 2 and regenerate at 0.9.0#2204happyhuman wants to merge 1 commit into
happyhuman wants to merge 1 commit into
Conversation
…0.9.0
The published Kotlin API reference has rendered 0.5.0 since it was last
generated, four releases behind `main`. The cause is not a forgotten manual
step: `generate.sh` cannot run against any adk-kotlin newer than v0.6.0.
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:
- `dokkaHtmlMultiModule` survives only as a disabled stub. `gradlew tasks`
against v0.9.0 lists it as `[V1 tasks disabled]`, so the build fails before
generating anything.
- Output moved from `build/dokka/htmlMultiModule` to `build/dokka/html`.
- The implicit root aggregation that produced the unified multi-module site is
gone. Dokka 2 wants 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.
The aggregation block is injected into the throwaway clone rather than sent
upstream, which keeps the fix inside adk-docs and lets the module list be a
docs decision instead of an SDK one.
Also adds a check that `index.html` renders the requested version. Nothing
verified this before, which is precisely how a 0.5.0 site sat in the repo
looking freshly built.
Module coverage changes, and not purely additively:
- Added: `integrations` (hosts BigQueryAgentAnalyticsPlugin, which
docs/integrations/bigquery-agent-analytics.md documents and the reference
never covered) and `testing`.
- Dropped: `examples`. It is sample code rather than API surface, and it
declares a JDK 21 toolchain that fails to auto-provision and takes the whole
build down with it.
- `firebase` and `mlkit` are aggregatable but emit empty directories — Dokka 2
generates no pages for their androidMain source sets. They are left out
rather than listed, since an empty module implies coverage that is not there.
Documenting them needs a source-set fix in adk-kotlin.
Verified: clean run of the committed script reproduces this tree; index.html
renders 0.9.0; no file under docs/api-reference/kotlin still contains 0.5.0;
the deep link at 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, skipping the eight
`navigation.html` fragments that have no `<head>`; and no temp-clone paths
leaked into the output.
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.
Leaves the reference one release behind the 1.0.0 pin in #2152 — that PR
re-runs this script once the v1.0.0 tag exists.
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 itand fixes the generator that made it impossible.
It is not a forgotten manual step.
tools/kotlin-api-docs/generate.shcannotrun 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:
dokkaHtmlMultiModulesurvives only as a disabledstub. Against a v0.9.0 clone,
./gradlew tasks --alllists it verbatim as:build/dokka/htmlMultiModuletobuild/dokka/html.from the subprojects; Dokka 2 requires an explicit
dependencies { dokka(project(...)) }block, and adk-kotlin's root build hasnone. 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 apost-generation check that
index.htmlactually 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.
core,a2a,litertlm,processor,webserverintegrationstestingexamplesfirebase,mlkitintegrationsmatters most. It hostsBigQueryAgentAnalyticsPlugin,which
docs/integrations/bigquery-agent-analytics.mddocuments and the APIreference has never covered.
examplesis 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.
firebaseandmlkitaggregate but emit empty directories — Dokka 2generates 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
index.htmlrenders0.9.0, and no file underdocs/api-reference/kotlin/still contains
0.5.0.docs/runtime/runconfig.md:364, intogoogle-adk-kotlin-core/com.google.adk.kt.agents/-run-config/— stillresolves.
navigation.htmlfragments, which have no<head>to inject into.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.0tag 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.