It’s my understanding that when I added the java version support, @Paul made a contribution to Gradle to add support upstream. I don’t think that PR has been merged (at least not since the last we checked). Since that PR has gone months without merger, even after requests to merge, we effectively don’t have the support from Gradle for the groovydoc enhancements. I’m not sure how we can get that support other than releasing our own plugin.
Grails created our own plugin only because of this deficit. I’m 100% in support of Groovy taking that plugin and publishing it as their own to accelerate feature delivery. It would be nice if Gradle would take code more regularly, but I think their lack of accepting our changes forces our hand here. -James On Tue, Apr 21, 2026 at 10:24 AM Paul King <[email protected]> wrote: > Here's another example: > > https://docs.groovy-lang.org/docs/next/html/gapi/groovy/xml/XmlSlurper.html > > This one has an XML snippet too. > > It should also honour light/dark mode if your OS supports it. So it > defaults to auto theme switching but you can force it to stay light or stay > dark. > > > On Tue, Apr 21, 2026 at 11:49 PM Guillaume Laforge <[email protected]> > wrote: > >> That's pretty cool to see the syntax highlighted in those snippets! >> >> On Tue, Apr 21, 2026 at 3:22 PM Paul King <[email protected]> wrote: >> >>> There is an example here: >>> >>> https://docs.groovy-lang.org/docs/next/html/gapi/groovy/sql/Sql.html >>> >>> It shows numerous groovy snippets and a SQL DDL example also highlighted >>> as SQL. >>> >>> You can also build from master using the normal groovydoc or >>> groovydocAll tasks (they are wired up to the Ant-based plugin). >>> >>> You can also get the docs or sdk zip from the artifacts of any recent >>> dist build, e.g. apache-groovy-docs-SNAPSHOT under: >>> https://github.com/apache/groovy/actions/runs/24721124182 >>> >>> Cheers, Paul. >>> >>> >>> On Tue, Apr 21, 2026 at 10:44 PM Guillaume Laforge <[email protected]> >>> wrote: >>> >>>> Hi Paul, >>>> >>>> Is there some new generated groovydoc online somewhere with those >>>> changes? >>>> >>>> Guillaume >>>> >>>> >>>> On Tue, Apr 21, 2026 at 2:41 PM Paul King <[email protected]> wrote: >>>> >>>>> Hi folks, >>>>> >>>>> The groovydoc tool hasn't had many updates in a while, so I thought >>>>> I'd try to change that. There is now a new version featuring: >>>>> >>>>> * snippets (mimicking JEP 413) and markdown doc-comment rendering >>>>> (mimicking JEP 467) >>>>> * customisable syntax highlighting with some dark/light mode support >>>>> * new commandline/Ant config options: showInternal, noIndex, >>>>> noDeprecatedList, noHelp, syntaxHighlighter, theme, addStylesheet, >>>>> additionalStylesheets, preLanguage >>>>> * new tags supported: @snippet, @highlight, @replace, @link (changed), >>>>> @start, @end, @apiNote, @implSpec, @implNote, @value, @param (changed), >>>>> @inheritDoc >>>>> >>>>> A nice thing about the snippet and markdown support is that it works >>>>> for JDK17+ for Java and Groovy files, instead of JDK18 (snippets) and >>>>> JDK23 >>>>> (markdown) when using javadoc. >>>>> >>>>> I merged the PR with only a short time for review because of the next >>>>> topic (Gradle support) meaning that most folks wouldn't have been able to >>>>> test it anyway. So commit then review seemed the only realistic option. I >>>>> can easily back out any bits that folks aren't happy with. >>>>> >>>>> Gotchas using Gradle's Groovydoc task >>>>> >>>>> The `org.gradle.api.tasks.javadoc.Groovydoc` task type shipped with >>>>> Gradle >>>>> predates all the improvements above, so the following settings are NOT >>>>> available via >>>>> the built-in task's DSL: >>>>> >>>>> - javaVersion >>>>> - showInternal >>>>> - noIndex, noDeprecatedList, noHelp >>>>> - syntaxHighlighter >>>>> - theme >>>>> - addStylesheet / additionalStylesheets >>>>> - preLanguage >>>>> >>>>> Setting any of those on a Gradle `Groovydoc` task has no effect. >>>>> Gradle does use Groovy's Ant task under the hood, but only passes through >>>>> the older property set. >>>>> >>>>> For our own Groovydoc needs, we have borrowed a copy of the Groovydoc >>>>> task from Grails, which gives us access to all the new features. At some >>>>> point we need to speak with them about maybe releasing this as an official >>>>> Gradle plugin. >>>>> >>>>> Let me know if you have any problems or suggestions for improvement. >>>>> >>>>> Cheers, Paul. >>>>> >>>>> >>>> >>>> -- >>>> *Guillaume Laforge* >>>> Apache Groovy committer >>>> Developer Advocate @ Google Cloud <https://cloud.google.com/> >>>> >>>> - Blog: glaforge.dev >>>> - X: @glaforge <http://twitter.com/glaforge> >>>> - Bluesky: @glaforge.dev <https://bsky.app/profile/glaforge.dev> >>>> - Mastodon: @[email protected] <http://%[email protected]/> >>>> >>>> >> >> -- >> *Guillaume Laforge* >> Apache Groovy committer >> Developer Advocate @ Google Cloud <https://cloud.google.com/> >> >> - Blog: glaforge.dev >> - X: @glaforge <http://twitter.com/glaforge> >> - Bluesky: @glaforge.dev <https://bsky.app/profile/glaforge.dev> >> - Mastodon: @[email protected] <http://%[email protected]/> >> >>
