Fix doc generation

Author: jdaugherty

.github/workflows/gradle.yml

@@ -80,14 +80,14 @@ jobs:
         id: docs
         env:
           GITHUB_MAVEN_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
-        run: ./gradlew docs --refresh-dependencies
+        run: ./gradlew docs:docs --refresh-dependencies
       - name: "📤 Publish docs to Github Pages"
         if: steps.docs.outcome == 'success'
         uses: grails/github-pages-deploy-action@v2
         env:
           TARGET_REPOSITORY: ${{ github.repository }}
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           BRANCH: gh-pages
-          FOLDER: build/docs
+          FOLDER: docs/build/docs
           COMMIT_EMAIL: grails-build@users.noreply.github.com
           COMMIT_NAME: grails-build

.github/workflows/release.yml

@@ -110,15 +110,15 @@ jobs:
       - name: "📖 Generate documentation"
         env:
           GITHUB_MAVEN_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
-        run: ./gradlew docs
+        run: ./gradlew docs:docs
       - name: "📤 Publish documentation to Github Pages"
         if: success()
         uses: grails/github-pages-deploy-action@grails
         env:
           BETA: ${{ contains(needs.publish.outputs.release_version, 'M') || contains(needs.publish.outputs.release_version, 'RC') }}
           GH_TOKEN: ${{ secrets.GH_TOKEN }}
           BRANCH: gh-pages
-          FOLDER: build/docs
+          FOLDER: docs/build/docs
           VERSION: ${{ needs.publish.outputs.release_version }}
           COMMIT_EMAIL: ${{ env.GIT_USER_EMAIL }}
           COMMIT_NAME: ${{ env.GIT_USER_NAME }}

build.gradle

@@ -46,5 +46,3 @@ subprojects {
         }
     }
 }
-
-apply from: rootProject.file("gradle/documentation-config.gradle")

docs/build.gradle

@@ -13,36 +13,75 @@ apply plugin: 'groovy'
 
 dependencies {
     implementation platform("org.grails:grails-bom:$grailsVersion")
+    implementation 'org.apache.groovy:groovy-groovydoc'
+    implementation 'org.apache.groovy:groovy-ant'
     implementation 'org.springframework:spring-core'
 }
 
 tasks.register('resolveSpringVersion') {
     group = 'documentation'
     description = 'Resolve Spring Version from the BOM'
+
     ext.resolved = configurations.compileClasspath
             .resolvedConfiguration
             .resolvedArtifacts
             .find {
                 it.moduleVersion.id.group == 'org.springframework' &&
                         it.moduleVersion.id.name.contains('spring-core')
             }.moduleVersion.id.version
+
     logger.lifecycle('Resolved Spring Framework version for Guide links: {}', resolved)
 }
 
+tasks.register('cleanDocs', Delete) {
+    group = 'documentation'
+    delete(project.layout.buildDirectory.dir('docs'))
+}
+
+tasks.register('aggregateGroovydoc', Groovydoc) {
+    group = 'documentation'
+    description = 'Copies Groovy API Documentation for all supporting projects'
+
+    Set<Project> groovyDocProjects = rootProject.subprojects.findAll {
+        it.name != 'docs' && !it.name.startsWith('example')
+    }
+    dependsOn(['cleanDocs'] + groovyDocProjects.collect { ":${it.name}:classes" as String })
+
+    source = groovyDocProjects.collectMany { prj ->
+        def dirs = []
+        // Always include main/groovy.
+        dirs += prj.sourceSets.main.groovy.srcDirs
 
-// TODO: PublishGuide should eventually ensure the build directory exists
-tasks.register('docsBuild') {
-    doFirst {
-        project.layout.buildDirectory.get().asFile.mkdirs()
+        // If this subproject defines an “ast” source set, include it.
+        def astSourceSet = prj.sourceSets.findByName('ast')
+        if (astSourceSet != null) {
+            dirs += astSourceSet.groovy.srcDirs
+        }
+        dirs
     }
-    // Do not cache this task since the directory must exist if publishGuide is going to run
-    outputs.upToDateWhen { false }
+
+    def groovydocClasspath = files(configurations.compileClasspath + groovyDocProjects.configurations.compileClasspath)
+    classpath = groovydocClasspath
+    groovyClasspath = groovydocClasspath
+
+    docTitle = "Grails Cache Plugin - ${project.version}"
+    access = GroovydocAccess.PROTECTED
+    includeAuthor = true
+    includeMainForScripts = false
+    processScripts = false
+
+    destinationDir = project.layout.buildDirectory.dir('docs/api').get().asFile
+
+    doLast { delete(project.layout.buildDirectory.dir('tmp')) }
+
+    inputs.files(source)
+    outputs.dir(destinationDir)
 }
 
 tasks.register('publishGuide', PublishGuide) {
     group = 'documentation'
     description = 'Generate Guide'
-    dependsOn('docsBuild', 'resolveSpringVersion')
+    dependsOn('aggregateGroovydoc', 'resolveSpringVersion')
 
     targetDir = project.layout.buildDirectory.dir('docs').get().asFile
     outputs.dir(targetDir) // ensure gradle understands what this task generates
@@ -78,3 +117,8 @@ tasks.register('publishGuide', PublishGuide) {
         '''.stripIndent(8)
     }
 }
+
+tasks.register('docs') {
+    group = 'documentation'
+    dependsOn('aggregateGroovydoc', 'publishGuide')
+}

docs/src/main/docs/guide/introduction.adoc

@@ -1,3 +1,3 @@
 The Grails Cache plugin provides powerful and easy to use caching functionality to Grails applications and plugins.
 
-IMPORTANT: Cache version 4.0.0 and higher requires GORM 6.1.x or higher
+IMPORTANT: Cache version 8.0.0 and higher requires Grails 7 or later.

docs/src/main/docs/guide/introduction/changeLog.adoc

@@ -1,7 +1,7 @@
 [[changeLog]]
 === Change log
 
-For recent versions please check the release notes https://github.com/grails-plugins/grails-cache/releases[here]
+For later versions please check the release notes https://github.com/grails-plugins/grails-cache/releases[here]
 
 === Version 4.0.0
 

docs/src/main/docs/guide/usage/unittests.adoc

@@ -5,12 +5,12 @@ method is invoked.
 
 [source,groovy]
 ----
-include::{sourcedir}/grails-app/services/com/demo/BasicCachingService.groovy[tags=get_data,indent=0]
+include::{exampleSourcedir}/grails-app/services/com/demo/BasicCachingService.groovy[tags=get_data,indent=0]
 ----
 
 [source,groovy]
 ----
-include::{sourcedir}/src/test/groovy/com/demo/BasicCachingServiceNoCacheManagerSpec.groovy[]
+include::{exampleSourcedir}/src/test/groovy/com/demo/BasicCachingServiceNoCacheManagerSpec.groovy[]
 ----
 
 In order for caching to be active when the unit test is running, cache manager
@@ -19,5 +19,5 @@ test.
 
 [source,groovy]
 ----
-include::{sourcedir}/src/test/groovy/com/demo/BasicCachingServiceSpec.groovy[]
+include::{exampleSourcedir}/src/test/groovy/com/demo/BasicCachingServiceSpec.groovy[]
 ----

example/build.gradle

@@ -71,4 +71,9 @@ bootRun {
 }
 
 apply from: rootProject.layout.projectDirectory.file('gradle/java-config.gradle')
-apply from: rootProject.layout.projectDirectory.file('gradle/test-config.gradle')
+apply from: rootProject.layout.projectDirectory.file('gradle/test-config.gradle')
+
+// no groovy doc for example
+tasks.withType(Groovydoc).configureEach {
+    enabled = false
+}

gradle/documentation-config.gradle

@@ -40,3 +40,8 @@ dependencies {
 
 apply from: rootProject.layout.projectDirectory.file('gradle/java-config.gradle')
 apply from: rootProject.layout.projectDirectory.file('gradle/test-config.gradle')
+
+// groovy docs will be generated by the docs project
+tasks.withType(Groovydoc).configureEach {
+    enabled = false
+}