Skip to content

Add JavaTemplated pipeline for java.base API docs - #28

Open
alexmmiller wants to merge 1 commit into
mainfrom
feature/java-base-docs-pipeline
Open

Add JavaTemplated pipeline for java.base API docs#28
alexmmiller wants to merge 1 commit into
mainfrom
feature/java-base-docs-pipeline

Conversation

@alexmmiller

Copy link
Copy Markdown
Collaborator

Summary

  • Adds JavaTemplated/: a self-contained pipeline that generates HTML API docs for OpenJDK 17's java.base module - Dokka (with the kdoc-to-json plugin from Dokka-plugin-kdoc2json/) produces JSON, then a small Pebble-based renderer (pebble-renderer/) turns that JSON into a mirrored HTML tree with working inter-page links.
  • Includes a required workaround for a genuine, still-open upstream Dokka bug (kotlin/dokka#2171) that otherwise crashes a full java.base run with a StackOverflowError in Dokka's own {@inheritDoc} resolver - 9 file pairs (18 of ~2,750 source files) are excluded from analysis. bisect_inheritdoc.py, the binary-search tool that found them, is included for future maintenance if a version bump reintroduces the crash elsewhere.
  • See JavaTemplated/README.md for the full pipeline walkthrough and prerequisites (a JDK 17 install, distinct from whatever this machine's default JDK is).

Test plan

  • Dokka-plugin-kdoc2json/kdoc-to-json builds and publishes to Maven local (./gradlew clean publishToMavenLocal)
  • dokka-java-base-docs generates JSON for the full java.base module (all ~2,750 source files, minus the 18 documented exclusions) via ./gradlew dokkaGenerateHtml with 0 failures
  • pebble-renderer renders all 22,209 resulting JSON files to HTML via ./gradlew run with 0 failures
  • Rendered HTML spot-checked for correct structure/signatures/links (internal .json cross-references rewritten to .html, both in template url fields and in doc-text {@link}-derived <a> tags)
  • Reviewer sanity-checks a sampled page or two from html-output/

🤖 Generated with Claude Code

…line for java.base

Generates HTML API docs for OpenJDK 17's java.base module: a Dokka project
(dokka-java-base-docs/) uses the kdoc-to-json plugin to emit JSON instead of HTML, then a
small Kotlin CLI (pebble-renderer/) renders that JSON through a Pebble template
(peb.peb.txt) into a mirrored HTML tree with working inter-page links.

Includes a required workaround for a genuine, still-open upstream Dokka bug
(Kotlin/dokka#2171) that otherwise crashes a full java.base run with a
StackOverflowError in Dokka's own {@inheritdoc} resolver - 9 file pairs (18 of ~2,750
source files) are excluded from analysis. bisect_inheritdoc.py, the tool that found
them via binary search, is included for future maintenance if a version bump
reintroduces the crash elsewhere.

See JavaTemplated/README.md for the full pipeline and prerequisites.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant