feat: publish Groovydoc Enhancer Plugin for use in end-user Grails apps#15430
Draft
jamesfredley wants to merge 8 commits into7.0.xfrom
Draft
feat: publish Groovydoc Enhancer Plugin for use in end-user Grails apps#15430jamesfredley wants to merge 8 commits into7.0.xfrom
jamesfredley wants to merge 8 commits into7.0.xfrom
Conversation
Replace Gradle's built-in Groovydoc task execution with AntBuilder to support the javaVersion parameter introduced in Groovy 4.0.27 (GROOVY-11668). This is needed because Gradle's Groovydoc task does not expose javaVersion (gradle/gradle#33659 is not merged), causing Java 17+ source parsing failures. Changes across all groovydoc configurations: - gradle/docs-dependencies.gradle: central config for ~90 modules and both aggregate tasks (aggregateGroovydoc, aggregateDataMappingGroovydoc) - gradle/docs-config.gradle: per-module source directory setup - grails-doc/build.gradle: aggregate task source directories - grails-data-docs/stage/build.gradle: data mapping aggregate source dirs - grails-gradle/gradle/docs-config.gradle: independent AntBuilder setup - grails-data-hibernate5/docs/build.gradle: added groovy-ant dependency and AntBuilder execution - grails-data-mongodb/docs/build.gradle: added groovy-ant dependency and AntBuilder execution - grails-forge/gradle/doc-config.gradle: AntBuilder without javaVersion (forge uses Groovy 3.0.25 which predates the feature) Closes #15385 Assisted-by: Claude Code <Claude@Claude.ai>
…ion plugin Move duplicated AntBuilder groovydoc execution, Matomo footer, documentation configuration registration, and task defaults into a shared convention plugin in build-logic. This eliminates ~490 lines of duplicated configuration across 8 build scripts while maintaining identical behavior. The plugin provides: - Documentation configuration registration with standard attributes - Common Groovydoc task defaults (author, timestamps, scripts) - AntBuilder-based execution with javaVersion support (Groovy 4.0.27+) - Matomo analytics footer - Source directory resolution from ext.groovydocSourceDirs or source sets - External documentation link support via ext.groovydocLinks - GrailsGroovydocExtension for per-project javaVersion control Build scripts retain project-specific configuration: dependencies, titles, source directories for aggregate tasks, and dynamic link resolution. Assisted-by: Claude Code <Claude@Claude.ai>
Separate GrailsGroovydocPlugin into a generic GroovydocEnhancerPlugin (with GroovydocEnhancerExtension) and a thin GrailsGroovydocPlugin that applies the base plugin and sets the Matomo footer. This makes the core AntBuilder groovydoc logic publishable and reusable by anyone, while keeping Grails-specific customizations in their own layer. The base plugin supports a useAntBuilder flag so projects can easily switch back to Gradle's built-in Groovydoc task if Gradle merges their javaVersion support (gradle/gradle#33659). Also fix a pre-existing bug in resolveProjectVersion() in docs-dependencies.gradle where the function never returned the resolved version string, causing all external groovydoc links (geb, testcontainers, spring, spring-boot) to be silently omitted. Assisted-by: Claude Code <Claude@Claude.ai>
Wrap the javaVersion convention in project.provider so the property is resolved at execution time rather than configuration time. Assisted-by: Claude Code <Claude@Claude.ai>
Add grails-gradle-groovydoc as a published Gradle plugin module that enables Grails applications using modern Java features (17+) to generate accurate Groovydoc documentation. Without this plugin, Groovydoc fails to parse Java sources using sealed classes, records, pattern matching, and other post-Java 11 language features. Changes: - New module grails-gradle/groovydoc with GroovydocEnhancerPlugin published as org.apache.grails.gradle:grails-gradle-groovydoc with plugin ID org.apache.grails.gradle.groovydoc - Forge DefaultFeature adds the plugin to all generated Grails apps - Profile base/profile.yml applies the plugin via grails CLI generation - grails-bom updated with the new artifact for BOM version management - build-logic retains its own copy for the framework build (bootstrap) Assisted-by: Claude Code <Claude@Claude.ai>
Contributor
Author
|
A Third "commons" build appears to be the only way to remove the duplication. |
Contributor
Author
|
Or moving it to a separate repo, as we have done with publishing. |
Contributor
|
In order to publish this, its going to have to go to a separate repository... |
Contributor
Author
|
@jdaugherty I will add that to agenda for the meeting, next week. |
Contributor
Author
|
This will either end up as a separate Apache Grails repo or possible over on Apache Groovy. |
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
3 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.
Summary
Potential path to allow end-user Grails applications to use modern Java features (17+) and still generate accurate Groovydoc documentation.
Gradle's built-in Groovydoc task does not expose the
javaVersionparameter (added in Groovy 4.0.27 via GROOVY-11668), so projects using Java 17+ features (sealed classes, records, pattern matching, text blocks, etc.) fail to generate Groovydoc. This PR publishes theGroovydocEnhancerPlugin(from #15420) as a standalone Gradle plugin that end-user Grails applications can consume.Changes
New Published Module:
grails-gradle-groovydocorg.apache.grails.gradle:grails-gradle-groovydocorg.apache.grails.gradle.groovydocgrails-gradle/groovydoc/following the existing grails-gradle subproject patterngrails-gradle-bom(subproject auto-inclusion)grails-bomviagradleBuildProjectsmap for end-user app BOM resolutionForge Integration (DefaultFeature)
GroovydocEnhancerfeature class applied to all generated Grails applications by defaultgrails-gradle-groovydocas a buildscript classpath dependency (version managed bygrails-bom)org.apache.grails.gradle.groovydocplugin viaapply pluginProfile Integration
base/profile.ymlto include the plugin forgrailsCLI-based app generationBuild-Logic
build-logic/retains its own copy of the plugin for the framework build itself (bootstrap constraint - build-logic cannot depend on grails-gradle artifacts without circular dependency)grails-gradle-groovydocmodule is the canonical version for end-user consumptionArchitecture Note
There are two copies of the enhancer plugin:
build-logic/plugins/- convention plugin for building grails-core itself (unpublished, internal)grails-gradle/groovydoc/- published plugin for end-user Grails appsThis duplication exists because
build-logicis evaluated beforegrails-gradlebuilds, creating a bootstrap dependency that preventsbuild-logicfrom consuming the published artifact directly. Future work could explore composite build substitution or a shared source set to eliminate this duplication.Testing
grails-gradle-groovydocbuilds successfully standalonegrails-bomPOM generation succeeds with the new artifactgrails-forge-corecompiles with the new feature classDepends On