Migrate doc generation to Dokka v2#2887
Open
wmathurin wants to merge 3 commits into
Open
Conversation
Replace the raw javadoc invocation in tools/generate_doc.sh with ./gradlew dokkaHtmlMultiModule. Add the Dokka Gradle plugin (1.9.20) to the buildscript classpath, apply it at the root for multi-module aggregation, and to all :libs:* subprojects for per-module docs. Output directory remains doc/ at the repo root.
- Bump dokka-gradle-plugin from 1.9.20 to 2.0.0
- Opt in to Dokka v2 mode via gradle.properties
- Replace subprojects{} apply + dokkaHtmlMultiModule task (v1 API)
with DokkaExtension DSL + dokka() dependencies (v2 API)
- Apply org.jetbrains.dokka to each lib subproject directly so Dokka
can resolve their source sets for aggregation
- Switch output format from Javadoc to unified Dokka HTML so that
doc/index.html is a proper multi-module site (Javadoc format does
not support true multi-module aggregation in v2)
- Update generate_doc.sh: dokkaHtmlMultiModule -> dokkaGeneratePublicationHtml
wmathurin
changed the title
Contributor
Author
Before
After
NB: javadoc did not document Kotlin classes |
Generated by 🚫 Danger |
Generated by 🚫 Danger |
Generated by 🚫 Danger |
…d into feature/migrate-doc-generation-to-dokka
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #2887 +/- ##
============================================
- Coverage 55.13% 55.09% -0.04%
- Complexity 2495 2504 +9
============================================
Files 226 226
Lines 17722 17781 +59
Branches 2311 2328 +17
============================================
+ Hits 9771 9797 +26
- Misses 6955 6980 +25
- Partials 996 1004 +8
🚀 New features to boost your workflow:
|
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
2 participants
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.
Why Dokka HTML instead of Javadoc format
The old workflow ran
javadoc -subpackages comacross all six source paths, producing a single flat site. Dokka v2'sdokka-javadocplugin generates per-module independent Javadoc sites — there is no built-in aggregation for the Javadoc format. ACopy-task merge is lossy (alphabetical index files andallclasses.htmlget overwritten per-module). The HTML format is the only Dokka format with proper multi-module aggregation, sodoc/index.htmlremains a complete, cross-linked API reference.