Add JavaTemplated pipeline for java.base API docs - #28
Open
alexmmiller wants to merge 1 commit into
Open
Conversation
…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.
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
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
JavaTemplated/: a self-contained pipeline that generates HTML API docs for OpenJDK 17'sjava.basemodule - Dokka (with thekdoc-to-jsonplugin fromDokka-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.java.baserun with aStackOverflowErrorin 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.JavaTemplated/README.mdfor 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-jsonbuilds and publishes to Maven local (./gradlew clean publishToMavenLocal)dokka-java-base-docsgenerates JSON for the fulljava.basemodule (all ~2,750 source files, minus the 18 documented exclusions) via./gradlew dokkaGenerateHtmlwith 0 failurespebble-rendererrenders all 22,209 resulting JSON files to HTML via./gradlew runwith 0 failures.jsoncross-references rewritten to.html, both in templateurlfields and in doc-text{@link}-derived<a>tags)html-output/🤖 Generated with Claude Code