Use 'grace-doc' Gradle plugin to generate documentation

Closes gh-64

Author: rainboyan

build.gradle

@@ -6,7 +6,6 @@ buildscript {
     dependencies {
         classpath "org.graceframework:grace-gradle-plugin:$graceVersion"
         classpath "io.github.gradle-nexus:publish-plugin:2.0.0"
-        classpath "org.asciidoctor:asciidoctor-gradle-jvm:3.3.2"
     }
 }
 
@@ -25,12 +24,13 @@ group = "org.graceframework.plugins"
 
 apply plugin: "eclipse"
 apply plugin: "idea"
+apply plugin: "groovy"
 apply plugin: "java-library"
+apply plugin: "org.graceframework.grace-doc"
 apply plugin: "org.graceframework.grace-plugin"
 apply plugin: "io.github.gradle-nexus.publish-plugin"
 apply plugin: "maven-publish"
 apply plugin: "signing"
-apply plugin: "org.asciidoctor.jvm.convert"
 
 repositories {
     mavenCentral()
@@ -88,29 +88,52 @@ java {
     withSourcesJar()
 }
 
-tasks.withType(Groovydoc) {
-    configure {
-        docTitle = "Grace Database Migration Plugin ${version}"
-        source = project.files('src/main/groovy')
-        destinationDir = new File(buildDir, 'docs/api')
-        classpath = configurations.documentation
-        groovyClasspath = configurations.documentation
-    }
-}
-
-task docs(type:Copy, group: 'documentation')  {
-    dependsOn(groovydoc, asciidoctor)
-    from "$buildDir/asciidoc"
-    into "$buildDir/docs"
-}
-
 jar {
     enabled = true
     archiveClassifier.set('plugin')
     includeEmptyDirs = false
     exclude 'testapp/*.class', 'databasemigration/*.class'
 }
 
+def cleanTask = project.tasks.findByName('clean')
+if (cleanTask == null) {
+    task clean(type: Delete) {
+        delete(buildDir)
+    }
+}
+else {
+    cleanTask.doLast {
+        ant.delete(dir: 'build/docs')
+    }
+}
+
+tasks.withType(Groovydoc) {
+    group = 'Documentation'
+    docTitle = "Grace Database Migration Plugin - ${project.version}"
+    destinationDir = project.file('build/docs/manual/api')
+    def files = []
+    project.rootProject.subprojects
+            .findAll { !it.name != 'docs' && !it.name.startsWith('examples') }
+            .each { subproject ->
+                if(subproject.file('src/main/groovy').exists()) {
+                    files += subproject.files('src/main/groovy')
+                }
+                if(subproject.file('src/main/java').exists()) {
+                    files += subproject.files('src/main/java')
+                }
+            }
+    if (project.file('src/main/groovy').exists()) {
+        files += project.files('src/main/groovy')
+    }
+    source = files
+    classpath += configurations.documentation
+}
+
+docs {
+    dependsOn groovydoc
+    sourceDir = project.file('src/docs')
+}
+
 publishing {
     publications {
         maven(MavenPublication) {

gradle.properties

@@ -2,9 +2,6 @@ projectVersion=6.3.0-SNAPSHOT
 graceVersion=2023.3.0-RC2
 gormVersion=2023.3.0-RC1
 gormHibernateVersion=2023.3.0-RC1
-websiteUrl=https://github.com/graceframework/grace-database-migration
-issueTrackerUrl=https://github.com/graceframework/grace-database-migration/issues
-vcsUrl=https://github.com/graceframework/grace-database-migration
 org.gradle.parallel=true
 org.gradle.caching=true
 org.gradle.daemon=true

settings.gradle

@@ -1 +1 @@
-rootProject.name = "database-migration"
+rootProject.name = "grace-database-migration"

src/docs/asciidoc/configuration.adoc src/docs/guide/configuration.adocsrc/docs/asciidoc/configuration.adoc renamed to src/docs/guide/configuration.adoc

@@ -1,25 +1,23 @@
 :includedir: _includes
-:integrationtestresources: ../../integration-test/resources
-
-== Configuration
+:integrationtestresources: src/integration-test/resources
 
 There are a few configuration options for the plugin. All configurations are prefixed with `grails.plugin.databasemigration`:
 
 [options="header"]
 |==================================
 |Property |Default |Meaning
-|changelogLocation |`grails-app/migrations` |the folder containing the main changelog file (which can include one or more other files)
+|changelogLocation |`app/migrations` |the folder containing the main changelog file (which can include one or more other files)
 |changelogFileName |`changelog.groovy` |the name of the main changelog file
 |changelogProperties |none |a map of properties to use for property substitution in Groovy DSL changelogs
-|contexts |none |A comma-delimited list of http://www.liquibase.org/manual/contexts[context] names. If specified, only changesets tagged with one of the context names will be run
-|dbDocLocation |`target/dbdoc` |the directory where the output from the <<ref-documentation-scripts-dbm-db-doc,dbm-db-doc>> script is written
+|contexts |none |A comma-delimited list of https://docs.liquibase.com/concepts/changelogs/attributes/contexts.html[context] names. If specified, only changesets tagged with one of the context names will be run
+|dbDocLocation |`build/dbdoc` |the directory where the output from the link:../ref/Documentation%20Scripts/dbm-db-doc.html[dbm-db-doc] script is written
 |dbDocController.enabled |`true` in dev mode |whether the /dbdoc/ url is accessible at runtime
 |dropOnStart |`false` |if `true` then drops all tables before auto-running migrations (if updateOnStart is true)
 |updateOnStart |`false` |if `true` then changesets from the specified list of names will be run at startup
 |updateOnStartFileName |none |the file name (relative to `changelogLocation`) to run at startup if `updateOnStart` is `true`
 |updateOnStartDefaultSchema |none |the default schema to use when running auto-migrate on start
-|updateOnStartContexts |none |A comma-delimited list of http://www.liquibase.org/manual/contexts[context] names. If specified, only changesets tagged with one of the context names will be run
-|updateAllOnStart |false |if `true` then changesets from the specified list of names will be run at startup for all dataSources. Useful for Grails Multitenancy with Multiple Databases (same db schema)
+|updateOnStartContexts |none |A comma-delimited list of https://docs.liquibase.com/concepts/changelogs/attributes/contexts.html[context] names. If specified, only changesets tagged with one of the context names will be run
+|updateAllOnStart |false |if `true` then changesets from the specified list of names will be run at startup for all dataSources. Useful for Grace Multitenancy with Multiple Databases (same db schema)
 |autoMigrateScripts |['RunApp'] |the scripts when running auto-migrate. Useful to run auto-migrate during test phase with: ['RunApp', 'TestApp']
 |excludeObjects |none |A comma-delimited list of database object names to ignore while performing a dbm-gorm-diff or dbm-generate-gorm-changelog
 |includeObjects |none |A comma-delimited list of database object names to look for while performing a dbm-gorm-diff or dbm-generate-gorm-changelog

src/docs/asciidoc/dbdoc.adoc src/docs/guide/dbdoc.adocsrc/docs/asciidoc/dbdoc.adoc renamed to src/docs/guide/dbdoc.adoc

@@ -1,6 +1,4 @@
-== DbDoc Controller
-
-You can use the <<ref-documentation-scripts-dbm-db-doc,dbm-db-doc>> script to generate static HTML files to view changelog information, but another option is to use the `DbDocController` at runtime. By default this controller is mapped to `/appname/dbdoc/` but this can be customized with `UrlMappings` like any controller.
+You can use the link:../ref/Documentation%20Scripts/dbm-db-doc.html[dbm-db-doc] script to generate static HTML files to view changelog information, but another option is to use the `DbDocController` at runtime. By default this controller is mapped to `/appname/dbdoc/` but this can be customized with `UrlMappings` like any controller.
 
 You probably don't want to expose this information to all of your application's users so by default the controller is only enabled in the development environment. But you can enable or disable it for any environment in `application.groovy` with the `dbDocController.enabled` config option. For example to enable for all environments (be sure to guard the URL with a security plugin in prod):
 

src/docs/asciidoc/generalUsage.adoc src/docs/guide/generalUsage.adocsrc/docs/asciidoc/generalUsage.adoc renamed to src/docs/guide/generalUsage.adoc

@@ -1,11 +1,9 @@
-== General Usage
-
 After creating the initial changelog, the typical workflow will be along the lines of:
 
 * make domain class changes that affect the schema
 * add changes to the changelog for them
 * backup your database in case something goes wrong
-* run `grails dbm-update` to update your development environment (or wherever you're applying the changes)
+* run `grace dbm-update` to update your development environment (or wherever you're applying the changes)
 * check the updated domain class(es) and changelog(s) into source control
 
 [WARNING]
@@ -14,7 +12,7 @@ After creating the initial changelog, the typical workflow will be along the lin
 2. Setting the dbCreate setting to "none" is recommended when executing the dbm migration commands. Otherwise you might run into troubles and the commands could not be executed.
 ====
 
-To create the changelog additions, you can either manually create the changes or with the <<ref-diff-scripts-dbm-gorm-diff,dbm-gorm-diff>> script (you can also use the <<ref-diff-scripts-dbm-diff,dbm-diff>> script but it's far less convenient and requires a 2nd temporary database).
+To create the changelog additions, you can either manually create the changes or with the link:../ref/Diff%20Scripts/dbm-gorm-diff.html[dbm-gorm-diff] script (you can also use the link:../ref/Diff%20Scripts/dbm-diff.html[dbm-diff] script but it's far less convenient and requires a 2nd temporary database).
 
 You have a few options with `dbm-gorm-diff`:
 

src/docs/asciidoc/gettingStarted.adoc src/docs/guide/gettingStarted.adocsrc/docs/asciidoc/gettingStarted.adoc renamed to src/docs/guide/gettingStarted.adoc

@@ -1,19 +1,17 @@
-== Getting Started
-
-*The first step is to add a dependency for the plugin in `build.gradle`:*
+The first step is to add a dependency for the plugin in `build.gradle`:
 
 [source,groovy,subs="attributes"]
 ----
 buildscript {
    dependencies {
       ...
-      classpath '{groupId}:{artifactId}:{version}'
+      classpath 'org.graceframework.plugins:database-migration:{version}'
    }
 }
 
 dependencies {
    ...
-     implementation '{groupId}:{artifactId}:{version}'
+     implementation 'org.graceframework.plugins:database-migration:{version}'
 }
 ----
 
@@ -23,19 +21,19 @@ It is also recommended to add a direct dependency to liquibase because Spring Bo
 ----
 dependencies {
    ...
-     implementation 'org.liquibase:liquibase-core:{liquibaseVersion}'
+     implementation 'org.liquibase:liquibase-core'
 }
 ----
 
-You should also tell Gradle about the migrations folder. If using Grails 4, make sure the configuration below is BEFORE the
+You should also tell Gradle about the migrations folder. If using Grace 4, make sure the configuration below is BEFORE the
 `dependencies` configuration, so that the `sourceSets` declaration takes effect.
 
 [source,groovy,subs="attributes"]
 ----
 sourceSets {
     main {
         resources {
-            srcDir 'grails-app/migrations'
+            srcDir 'db/migrations'
         }
     }
 }
@@ -47,61 +45,61 @@ Next you'll need to create an initial changelog. You can use Liquibase XML or th
 
 Depending on the state of your database and code, you have two options; either create a changelog from the database or create it from your domain classes. The decision tends to be based on whether you prefer to design the database and adjust the domain classes to work with it, or to design your domain classes and use Hibernate to create the corresponding database structure.
 
-To create a changelog from the database, use the <<ref-rollback-scripts-dbm-generate-changelog,dbm-generate-changelog>> script:
+To create a changelog from the database, use the link:../ref/Rollback%20Scripts/dbm-generate-changelog.html[dbm-generate-changelog] script:
 [source,groovy]
 ----
-grails dbm-generate-changelog changelog.groovy
+grace dbm-generate-changelog changelog.groovy
 ----
 
 or
 
 [source,groovy]
 ----
-grails dbm-generate-changelog changelog.xml
+grace dbm-generate-changelog changelog.xml
 ----
 
-depending on whether you prefer the Groovy DSL or XML. The filename is relative to the changelog base folder, which defaults to `grails-app/migrations`.
+depending on whether you prefer the Groovy DSL or XML. The filename is relative to the changelog base folder, which defaults to `app/migrations`.
 
 NOTE: If you use the XML format (or use a non-default Groovy filename), be sure to change the name of the file in `application.groovy` so `dbm-update` and other scripts find the file:
 [source,groovy]
 ----
 grails.plugin.databasemigration.changelogFileName = 'changelog.xml'
 ----
 
-Since the database is already correct, run the <<ref-maintenance-scripts-dbm-changelog-sync,dbm-changelog-sync>> script to record that the changes have already been applied:
+Since the database is already correct, run the link:../ref/Maintenance%20Scripts/dbm-changelog-sync.html[dbm-changelog-sync] script to record that the changes have already been applied:
 [source,groovy]
 ----
-grails dbm-changelog-sync
+grace dbm-changelog-sync
 ----
 
 Running this script is primarily a no-op except that it records the execution(s) in the Liquibase DATABASECHANGELOG table.
 
-To create a changelog from your domain classes, use the <<ref-rollback-scripts-dbm-generate-gorm-changelog,dbm-generate-gorm-changelog>> script:
+To create a changelog from your domain classes, use the link:../ref/Rollback%20Scripts/dbm-generate-gorm-changelog.html[dbm-generate-gorm-changelog] script:
 
 [source,groovy]
 ----
-grails dbm-generate-gorm-changelog changelog.groovy
+grace dbm-generate-gorm-changelog changelog.groovy
 ----
 
 or
 
 [source,groovy]
 ----
-grails dbm-generate-gorm-changelog changelog.xml
+grace dbm-generate-gorm-changelog changelog.xml
 ----
 
-If you haven't created the database yet, run the <<ref-update-scripts-dbm-update,dbm-update>> script to create the corresponding tables:
+If you haven't created the database yet, run the link:../ref/Update%20Scripts/dbm-update.html[dbm-update] script to create the corresponding tables:
 
 [source,groovy]
 ----
-grails dbm-update
+grace dbm-update
 ----
 
-or the <<ref-maintenance-scripts-dbm-changelog-sync,dbm-changelog-sync>> script if the database is already in sync with your code:
+or the link:../ref/Maintenance%20Scripts/dbm-changelog-sync.html[dbm-changelog-sync] script if the database is already in sync with your code:
 
 [source,groovy]
 ----
-grails dbm-changelog-sync
+grace dbm-changelog-sync
 ----
 
 *Source control*

src/docs/asciidoc/gorm.adoc src/docs/guide/gorm.adocsrc/docs/asciidoc/gorm.adoc renamed to src/docs/guide/gorm.adoc

@@ -1,5 +1,3 @@
-== GORM Support
-
 The plugin's support for GORM is one feature that differentiates it from using Liquibase directly. Typically, when using Liquibase you make changes to a database yourself, and then create changesets manually, or use a diff script to compare your updated database to one that hasn't been updated yet. This is a decent amount of work and is rather error-prone. It's easy to forget some changes that aren't required but help performance, for example creating an index on a foreign key when using MySQL.
 
 *create-drop, create, and update*
@@ -22,4 +20,4 @@ So a good workflow would be:
 
 *dbm-generate-gorm-changelog*
 
-The <<ref-rollback-scripts-dbm-generate-gorm-changelog,dbm-generate-gorm-changelog>> script is useful for when you want to switch from `create-drop` mode to doing proper migrations. It's not very useful if you already have a database that's in sync with your code, since you can just use the <<ref-rollback-scripts-dbm-generate-changelog,dbm-generate-changelog>> script that creates a changelog from your database.
+The link:../ref/Rollback%20Scripts/dbm-generate-gorm-changelog.html[dbm-generate-gorm-changelog] script is useful for when you want to switch from `create-drop` mode to doing proper migrations. It's not very useful if you already have a database that's in sync with your code, since you can just use the link:../ref/Rollback%20Scripts/dbm-generate-changelog.html[dbm-generate-changelog] script that creates a changelog from your database.

src/docs/asciidoc/groovyChanges.adoc src/docs/guide/groovyChanges.adocsrc/docs/asciidoc/groovyChanges.adoc renamed to src/docs/guide/groovyChanges.adoc

@@ -1,6 +1,4 @@
-== Groovy Changes
-
-In addition to the built-in Liquibase changes (see http://www.liquibase.org/manual/home[the documentation] for what's available) you can also make database changes using Groovy code (as long as you're using the Groovy DSL file format). These changes use the `grailsChange` tag name and are contained in a `changeSet` tag like standard built-in tags.
+In addition to the built-in https://docs.liquibase.com/concepts/changelogs/home.html[Liquibase changes] you can also make database changes using Groovy code (as long as you're using the Groovy DSL file format). These changes use the `grailsChange` tag name and are contained in a `changeSet` tag like standard built-in tags.
 
 There are four supported inner tags and two callable methods (to override the default confirmation message and checksum value).
 

…c/docs/asciidoc/groovyPreconditions.adoc src/docs/guide/groovyPreconditions.adocsrc/docs/asciidoc/groovyPreconditions.adoc renamed to src/docs/guide/groovyPreconditions.adoc src/docs/asciidoc/groovyPreconditions.adoc renamed to src/docs/guide/groovyPreconditions.adoc

@@ -1,6 +1,4 @@
-== Groovy Preconditions
-
-In addition to the built-in Liquibase preconditions (see http://www.liquibase.org/manual/preconditions[the documentation] for what's available) you can also specify preconditions using Groovy code (as long as you're using the Groovy DSL file format). These changes use the `grailsPrecondition` tag name and are contained in the `databaseChangeLog` tag or in a `changeSet` tag like standard built-in tags.
+In addition to the built-in https://docs.liquibase.com/concepts/changelogs/preconditions[Liquibase preconditions] you can also specify preconditions using Groovy code (as long as you're using the Groovy DSL file format). These changes use the `grailsPrecondition` tag name and are contained in the `databaseChangeLog` tag or in a `changeSet` tag like standard built-in tags.
 
 === General format