#13552 Integrate docs from grails/grails-testing-support into grails-doc

build.gradle

@@ -1,7 +1,6 @@
 plugins {
     id 'base'
     id 'org.asciidoctor.jvm.convert' version '4.0.3'
-    id 'org.grails.grails-gdoc-to-asciidoc'
     id 'groovy'
 }
 
@@ -16,44 +15,24 @@ import org.apache.tools.ant.taskdefs.condition.Os
 version = project.findProperty("grails.version")
 archivesBaseName = "grails-docs"
 
-ext.checkOutDir = project.layout.buildDirectory.dir('checkout').get().asFile.absolutePath
+ext.grailsCheckOutDir = project.layout.buildDirectory.dir('grails-core/checkout').get().asFile.absolutePath
+ext.grailsTestsCheckOutDir = project.layout.buildDirectory.dir('grails-functional-tests/checkout').get().asFile.absolutePath
 ext.outputDir = layout.buildDirectory.file("docs").get().asFile.absolutePath
 ext.githubSlug = "grails/grails-doc"
 ext.githubBranch = project.findProperty("githubBranch") ?: "7.0.x"
 ext.guidePage = "/docs/guide/single.html"
 ext.indexPage = "/docs/index.html"
 
 ext.explicitGrailsHome = System.getProperty("grails.home") ?: project.findProperty('grails.home')
-ext.grailsHome = explicitGrailsHome ? file(explicitGrailsHome).absolutePath : "${checkOutDir}/grails-src"
+ext.grailsHome = explicitGrailsHome ? file(explicitGrailsHome).absolutePath : "${grailsCheckOutDir}/grails-src"
+ext.explicitGrailsFunctionalTestsHome = System.getProperty("grails.functional.test.home") ?: project.findProperty('grails.functional.test.home')
+ext.grailsTestsHome = explicitGrailsFunctionalTestsHome ? file(explicitGrailsFunctionalTestsHome).absolutePath : "${grailsTestsCheckOutDir}/grails-functional-tests-src"
 ext.projectVersion = project.version
 
-configurations {
-    publish
-    configureEach {
-        resolutionStrategy.eachDependency { DependencyResolveDetails details ->
-            if ((details.requested.group == 'org.codehaus.groovy' || details.requested.group == 'org.apache.groovy') && details.requested.name != 'groovy-bom') {
-                details.useTarget(group: 'org.apache.groovy', name: details.requested.name, version: "$groovyVersion")
-                details.because "The dependency coordinates are changed in Apache Groovy 4, plus ensure version"
-            }
-        }
-    }
-}
-
-gdoc2asciidoc {
-    apiLinks = ['org.hibernate'             : 'https://docs.jboss.org/hibernate/orm/current/javadocs/',
-                'org.springframework.boot'  : "https://docs.spring.io/spring-boot/docs/$springBootVersion/api",
-                'org.springframework'       : "https://docs.spring.io/spring/docs/$springVersion/javadoc-api/",
-                'jakarta.servlet'           : 'https://jakarta.ee/specifications/servlet/6.0/',
-                'java.'                     : 'https://docs.oracle.com/en/java/javase/17/docs/api/',
-                'groovy.'                   : 'https://docs.groovy-lang.org/docs/latest/html/api/',
-                'org.codehaus.groovy.grails': "https://docs.grails.org/$githubBranch/api",
-                'grails.orm.'               : 'https://gorm.grails.org/latest/api',
-                'grails.gorm.'              : 'https://gorm.grails.org/latest/api',
-                'grails.'                   : "https://docs.grails.org/$githubBranch/api",
-                'org.grails.'               : "https://docs.grails.org/$githubBranch/api"
-    ]
-    resourcesDir = file("resources")
-    srcDir = file("src/en")
+dependencies {
+    implementation platform("org.grails:grails-bom:${project['grails.version']}")
+    implementation "org.grails:grails-docs"
+    implementation "org.apache.groovy:groovy"
 }
 
 task buildscriptDependencies(type: DependencyReportTask) {
@@ -111,17 +90,21 @@ tasks.register('fetchGrailsSource', grails.doc.FetchGrailsSourceTask) {
     onlyIf { !explicitGrailsHome }
 }
 
+tasks.register('fetchGrailsTestsSource', grails.doc.FetchGrailsTestsSourceTask) {
+    onlyIf { !explicitGrailsTestsHome }
+}
+
 tasks.register("editProjectArtificat", Exec) {
     onlyIf { project.hasProperty("editGrailsVersion") }
-    dependsOn 'fetchGrailsSource'
+    dependsOn 'fetchGrailsSource', 'fetchGrailsTestsSource'
 
     executable Os.isFamily(Os.FAMILY_WINDOWS) ? "cmd" : "bash"
     args Os.isFamily(Os.FAMILY_WINDOWS) ? "/c" : "-c", "sed -i 's/^projectVersion.*\$/projectVersion=$version/' ${grailsHome}/gradle.properties"
 }
 
 tasks.register("apiDocs", Exec) {
     onlyIf { !System.getProperty("disable.groovydocs") }
-    dependsOn 'fetchGrailsSource'
+    dependsOn 'fetchGrailsSource', 'fetchGrailsTestsSource'
 
     inputs.files(fileTree(grailsHome) {
         exclude '**/*.lock'
@@ -144,8 +127,21 @@ tasks.register('extractPomVersions', grails.doc.ExtractPomVersionsTask) {
     pomFile = downloadPom.outputs.files.singleFile
 }
 
+tasks.register('resolveGroovyVersion') {
+    group = 'documentation'
+    description = 'Resolve Groovy Version from the BOM'
+    ext.resolved = configurations.compileClasspath
+            .resolvedConfiguration
+            .resolvedArtifacts
+            .find {
+                it.moduleVersion.id.group == 'org.apache.groovy' &&
+                        it.moduleVersion.id.name.contains('groovy')
+            }.moduleVersion.id.version
+    logger.lifecycle('Resolved Groovy version for Guide links: {}', resolved)
+}
+
 tasks.register('publishGuide', grails.doc.gradle.PublishGuide) {
-    dependsOn(['apiDocs', 'extractPomVersions', 'jar'])
+    dependsOn(['apiDocs', 'extractPomVersions', 'jar', 'resolveGroovyVersion'])
     targetDir = project.layout.buildDirectory.dir("manual").get().asFile
 
     doFirst {
@@ -163,9 +159,10 @@ tasks.register('publishGuide', grails.doc.gradle.PublishGuide) {
         propertiesFiles = [new File(projectDir, "gradle.properties")]
         asciidoc = true
         properties = [
+                'safe'     : 'UNSAFE',
                 'jakartaee'          : "https://jakarta.ee/specifications/platform/10/apidocs/",
                 'javase'             : "https://docs.oracle.com/en/java/javase/17/docs/api/",
-                'groovyapi'          : "https://docs.groovy-lang.org/${groovyVersion}/html/gapi/",
+                'groovyapi'          : "https://docs.groovy-lang.org/${resolveGroovyVersion.resolved}/html/gapi/",
                 'springapi'          : "https://docs.spring.io/spring/docs/${springVersion}/javadoc-api/",
                 'springdocs'         : "https://docs.spring.io/spring/docs/${springVersion}/",
                 'gspdocs'            : "https://gsp.grails.org/${gspVersion}",
@@ -176,7 +173,11 @@ tasks.register('publishGuide', grails.doc.gradle.PublishGuide) {
                 'springBootReference': "https://docs.spring.io/spring-boot/docs/${springBootVersion}/reference",
                 'springBootVersion'  : project.springBootVersion,
                 'springVersion'      : project.springVersion,
-                'gradleVersion'      : project.gradleVersion
+                'gradleVersion'      : project.gradleVersion,
+                'GrailsVersion'      : project['grails.version'],
+                'version'      : project['grails.version'],
+                'sourcedir'          : grailsHome,
+                'functionalSourceDir': grailsTestsHome,
         ]
         // Parse the string content into Properties object
         def props = new Properties()

buildSrc/build.gradle

@@ -8,20 +8,8 @@ repositories {
 
 compileJava.options.release = 17
 
-configurations {
-    configureEach {
-        resolutionStrategy.eachDependency { DependencyResolveDetails details ->
-            if ((details.requested.group == 'org.codehaus.groovy' || details.requested.group == 'org.apache.groovy') && details.requested.name != 'groovy-bom') {
-                details.useTarget(group: 'org.apache.groovy', name: details.requested.name, version: "$groovyVersion")
-                details.because "The dependency coordinates are changed in Apache Groovy 4, plus ensure version"
-            }
-        }
-    }
-}
-
 dependencies {
-    implementation "org.grails:grails-docs:${grailsDocsVersion}"
-    implementation "org.apache.groovy:groovy:$groovyVersion"
-    implementation "org.grails:grails-gdoc-engine:1.0.1"
-    implementation "org.grails:gdoc-to-asciidoc:1.0.1"
+    implementation platform("org.grails:grails-bom:$grailsDocsVersion")
+    implementation "org.grails:grails-docs"
+    implementation "org.apache.groovy:groovy"
 }

buildSrc/src/main/groovy/grails/doc/FetchGrailsSourceTask.groovy

@@ -38,32 +38,32 @@ abstract class FetchGrailsSourceTask extends DefaultTask {
     String grailsVersion = System.getenv('TARGET_GRAILS_VERSION')
 
     @OutputDirectory
-    def checkOutDir = project.findProperty('checkOutDir') ?: project.layout.buildDirectory.dir("checkout")
+    def grailsCheckOutDir = project.findProperty('grailsCheckOutDir') ?: project.layout.buildDirectory.dir("grails-core/checkout")
 
     @TaskAction
     void fetchGrailsSource() {
         if (!explicitGrailsHome) {
-            ant.mkdir(dir: checkOutDir)
+            ant.mkdir(dir: grailsCheckOutDir)
 
             println "Downloading Grails source code. If you already have a copy " +
                     "of the Grails source code checked out you can avoid this download " +
                     "by setting the grails.home system property to point to your local " +
                     "copy of the source. See README.md for more information."
 
-            def zipFile = "${checkOutDir}/grails-src.zip"
+            def zipFile = "${grailsCheckOutDir}/grails-src.zip"
             if (grailsVersion) {
                 ant.get(src: "https://github.com/grails/grails-core/archive/refs/tags/v${grailsVersion}.zip", dest: zipFile, verbose: true)
             } else {
                 ant.get(src: "https://github.com/grails/grails-core/zipball/${project.githubBranch}", dest: zipFile, verbose: true)
             }
 
-            ant.unzip(src: zipFile, dest: checkOutDir) {
+            ant.unzip(src: zipFile, dest: grailsCheckOutDir) {
                 mapper(type: "regexp", from: "(grails-core-\\S*?/)(.*)", to: "grails-src/\\2")
             }
 
-            ant.chmod(file: "${checkOutDir}/grails-src/gradlew", perm: 700)
+            ant.chmod(file: "${grailsCheckOutDir}/grails-src/gradlew", perm: 700)
 
-            println "Grails source code has been downloaded to ${checkOutDir}"
+            println "Grails source code has been downloaded to ${grailsCheckOutDir}"
         } else {
             println "GRAILS HOME=${explicitGrailsHome}"
         }

buildSrc/src/main/groovy/grails/doc/FetchGrailsTestsSourceTask.groovy

@@ -0,0 +1,72 @@
+/**
+ * Copyright 2024 The Unity Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package grails.doc
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.Optional
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+
+/**
+ * Task to fetch the Grails source code.
+ *
+ * @author Puneet Behl
+ * @since 6.2.0
+ */
+abstract class FetchGrailsTestsSourceTask extends DefaultTask {
+
+    @Optional
+    @Input
+    String explicitGrailsTestsHome = project.findProperty('grails.functional.test.home') ?: null
+
+    @Optional
+    @Input
+    String grailsVersion = System.getenv('TARGET_GRAILS_VERSION')
+
+    @OutputDirectory
+    def grailsTestsCheckOutDir = project.findProperty('grailsTestsCheckOutDir') ?: project.layout.buildDirectory.dir("grails-functional-tests/checkout")
+
+    @TaskAction
+    void fetchGrailsTestsSource() {
+        if (!explicitGrailsTestsHome) {
+            ant.mkdir(dir: grailsTestsCheckOutDir)
+
+            println "Downloading Grails Functional Tests source code. If you already have a copy " +
+                    "of the Grails Functional Tests source code checked out you can avoid this download " +
+                    "by setting the grails.functional.test.home system property to point to your local " +
+                    "copy of the source. See README.md for more information."
+
+            def zipFile = "${grailsTestsCheckOutDir}/grails-src.zip"
+            if (grailsVersion) {
+                ant.get(src: "https://github.com/grails/grails-functional-tests/archive/refs/heads/${grailsVersion.replaceFirst(/^(\d+\.\d+)\..*/, '$1.x')}.zip", dest: zipFile, verbose: true)
+            } else {
+                ant.get(src: "https://github.com/grails/grails-functional-tests/zipball/${project.githubBranch}", dest: zipFile, verbose: true)
+            }
+
+            ant.unzip(src: zipFile, dest: grailsTestsCheckOutDir) {
+                mapper(type: "regexp", from: "(grails-functional-tests-\\S*?/)(.*)", to: "grails-functional-test-src/\\2")
+            }
+
+            ant.chmod(file: "${grailsTestsCheckOutDir}/grails-functional-test-src/gradlew", perm: 700)
+
+            println "Grails Functional Tests source code has been downloaded to ${grailsTestsCheckOutDir}"
+        } else {
+            println "GRAILS TESTS HOME=${explicitGrailsTestsHome}"
+        }
+    }
+}
+

src/en/guide/async/events.adoc

@@ -38,4 +38,8 @@ The following table summarizes async framework support and the necessary depende
 |`grails-events-rxjava2`
 |`org.grails.events.rxjava2.RxEventBus`
 
+|RxJava 3.x
+|`grails-events-rxjava3`
+|`org.grails.events.rxjava3.RxEventBus`
+
 |===

src/en/guide/async/events/asyncConsuming.adoc

@@ -7,7 +7,7 @@ For example:
 ----
 import grails.events.annotation.*
 ...
-include::{sourcedir}/grails-async/grails-events-transform/src/test/groovy/grails/events/annotation/PubSubSpec.groovy[tags=subscriber]
+include::{sourcedir}/grails-events/transform/src/test/groovy/grails/events/annotation/PubSubSpec.groovy[tags=subscriber]
 ----
 
 In this example, every time a `sum` event occurs the subscriber will be invoked.
@@ -27,7 +27,7 @@ If you wish to subscribe to events dynamically or need more flexibility, then an
 import grails.events.bus.EventBusAware
 import jakarta.annotation.PostConstruct
 ...
-include::{sourcedir}/grails-async/grails-events-transform/src/test/groovy/grails/events/ManualPubSubSpec.groovy[tags=subscriber]
+include::{sourcedir}/grails-events/transform/src/test/groovy/grails/events/ManualPubSubSpec.groovy[tags=subscriber]
 ----
 
 In this example the `TotalService` calls `subscribe` and passes a closure within a method called `init`. The `init` method is annotated with the annotation `@PostConstruct` so that is called after the `EventBus` has been injected by Spring, ensuring it is only called once and the events are correctly subscribed to.

src/en/guide/async/events/asyncNotifying.adoc

@@ -7,7 +7,7 @@ For example:
 ----
 import grails.events.annotation.*
 ...
-include::{sourcedir}/grails-async/grails-events-transform/src/test/groovy/grails/events/annotation/PubSubSpec.groovy[tags=publisher]
+include::{sourcedir}/grails-events/transform/src/test/groovy/grails/events/annotation/PubSubSpec.groovy[tags=publisher]
 ----
 
 What the above does is take the return value of the method and publish an event using an event `id` that is the same as the method name.
@@ -26,7 +26,7 @@ If you want more flexiblity then you could simulate the behaviour of annotation
 ----
 import grails.events.*
 ...
-include::{sourcedir}/grails-async/grails-events-transform/src/test/groovy/grails/events/ManualPubSubSpec.groovy[tags=publisher]
+include::{sourcedir}/grails-events/transform/src/test/groovy/grails/events/ManualPubSubSpec.groovy[tags=publisher]
 ----
 
 Notice in the above example, the link:{asyncApi}/grails/events/EventPublisher.html[EventPublisher] trait is explicitly implemented.