Use 'grace-doc' Gradle plugin to generate documentation

Closes gh-66

Author: rainboyan

build.gradle

@@ -24,7 +24,9 @@ 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: "org.graceframework.grace-gsp"
 apply plugin: "io.github.gradle-nexus.publish-plugin"
@@ -83,12 +85,6 @@ dependencies {
     }
 }
 
-groovydoc.doFirst {
-    classpath += (configurations.documentation + configurations.compileClasspath)
-}
-
-bootJar.enabled = false
-
 java {
     toolchain {
         languageVersion = JavaLanguageVersion.of(17)
@@ -105,6 +101,46 @@ tasks.named('compileJava') {
     inputs.files(tasks.named('processResources'))
 }
 
+
+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 Fields - ${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

@@ -7,11 +7,6 @@ javaParserCoreVersion=3.26.4
 joddWotVersion=3.3.8
 objenesisVersion=3.4
 scaffoldingVersion=6.3.0-RC1
-asciidoc=true
-githubSlug=graceframework/grace-fields
-githubBranch=master
-title=Grace Fields Plugin
-projectDesc=Customizable form-field rendering based on overrideable GSP template
-guide=../../guide
-projectUrl=https://github.com/graceframework/grace-fields
-developers=Michael Yan
+org.gradle.parallel=true
+org.gradle.caching=true
+org.gradle.daemon=true

…ocs/guide/customizingFieldRendering.adoc …ocs/guide/customizingFieldRendering.adocsrc/main/docs/guide/customizingFieldRendering.adoc renamed to src/docs/guide/customizingFieldRendering.adoc src/main/docs/guide/customizingFieldRendering.adoc renamed to src/docs/guide/customizingFieldRendering.adoc

@@ -27,7 +27,7 @@ names are summarized below:
 
 
 Users upgrading to 1.5 from a previous version should either rename their templates (recommended) or add the following
-to `grails-app/conf/application.yml` to change the default templates names to the old names
+to `app/conf/application.yml` to change the default templates names to the old names
 
 [source,groovy]
 ----
@@ -46,42 +46,42 @@ grails:
 
 The template for a field is chosen by a convention using the names of the controller, action, bean class, bean property, theme, etc. All the tags will look for templates in the following directories in decreasing order of preference:
 
-* `grails-app/views/*controllerNamespace*/*controllerName*/*actionName*/*propertyName*/_themes/*themeName*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*actionName*/_themes/*themeName*/*propertyType*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*actionName*/_themes/*themeName*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*propertyName*/_themes/*themeName*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/_themes/*themeName*/*propertyType*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/_themes/*themeName*/`
-* `grails-app/views/*controllerName*/*actionName*/*propertyName*/_themes/*themeName*/`
-* `grails-app/views/*controllerName*/*actionName*/_themes/*themeName*/*propertyType*/`
-* `grails-app/views/*controllerName*/*actionName*/_themes/*themeName*/`
-* `grails-app/views/*controllerName*/*propertyName*/_themes/*themeName*/`
-* `grails-app/views/*controllerName*/_themes/*themeName*/*propertyType*/`
-* `grails-app/views/*controllerName*/_themes/*themeName*/`
-* `grails-app/views/_fields/_themes/*themeName*/*class*/*propertyName*/`
-* `grails-app/views/_fields/_themes/*themeName*/*superclass*/*propertyName*/`
-* `grails-app/views/_fields/_themes/*themeName*/*associationType*/`
-* `grails-app/views/_fields/_themes/*themeName*/*propertyType*/`
-* `grails-app/views/_fields/_themes/*themeName*/*propertySuperclass*/`
-* `grails-app/views/_fields/_themes/*themeName*/default/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*actionName*/*propertyName*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*actionName*/*propertyType*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*actionName*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*propertyName*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/*propertyType*/`
-* `grails-app/views/*controllerNamespace*/*controllerName*/`
-* `grails-app/views/*controllerName*/*actionName*/*propertyName*/`
-* `grails-app/views/*controllerName*/*actionName*/*propertyType*/`
-* `grails-app/views/*controllerName*/*actionName*/`
-* `grails-app/views/*controllerName*/*propertyName*/`
-* `grails-app/views/*controllerName*/*propertyType*/`
-* `grails-app/views/*controllerName*/`
-* `grails-app/views/_fields/*class*/*propertyName*/`
-* `grails-app/views/_fields/*superclass*/*propertyName*/`
-* `grails-app/views/_fields/*associationType*/`
-* `grails-app/views/_fields/*propertyType*/`
-* `grails-app/views/_fields/*propertySuperclass*/`
-* `grails-app/views/_fields/default/`
+* `app/views/*controllerNamespace*/*controllerName*/*actionName*/*propertyName*/_themes/*themeName*/`
+* `app/views/*controllerNamespace*/*controllerName*/*actionName*/_themes/*themeName*/*propertyType*/`
+* `app/views/*controllerNamespace*/*controllerName*/*actionName*/_themes/*themeName*/`
+* `app/views/*controllerNamespace*/*controllerName*/*propertyName*/_themes/*themeName*/`
+* `app/views/*controllerNamespace*/*controllerName*/_themes/*themeName*/*propertyType*/`
+* `app/views/*controllerNamespace*/*controllerName*/_themes/*themeName*/`
+* `app/views/*controllerName*/*actionName*/*propertyName*/_themes/*themeName*/`
+* `app/views/*controllerName*/*actionName*/_themes/*themeName*/*propertyType*/`
+* `app/views/*controllerName*/*actionName*/_themes/*themeName*/`
+* `app/views/*controllerName*/*propertyName*/_themes/*themeName*/`
+* `app/views/*controllerName*/_themes/*themeName*/*propertyType*/`
+* `app/views/*controllerName*/_themes/*themeName*/`
+* `app/views/_fields/_themes/*themeName*/*class*/*propertyName*/`
+* `app/views/_fields/_themes/*themeName*/*superclass*/*propertyName*/`
+* `app/views/_fields/_themes/*themeName*/*associationType*/`
+* `app/views/_fields/_themes/*themeName*/*propertyType*/`
+* `app/views/_fields/_themes/*themeName*/*propertySuperclass*/`
+* `app/views/_fields/_themes/*themeName*/default/`
+* `app/views/*controllerNamespace*/*controllerName*/*actionName*/*propertyName*/`
+* `app/views/*controllerNamespace*/*controllerName*/*actionName*/*propertyType*/`
+* `app/views/*controllerNamespace*/*controllerName*/*actionName*/`
+* `app/views/*controllerNamespace*/*controllerName*/*propertyName*/`
+* `app/views/*controllerNamespace*/*controllerName*/*propertyType*/`
+* `app/views/*controllerNamespace*/*controllerName*/`
+* `app/views/*controllerName*/*actionName*/*propertyName*/`
+* `app/views/*controllerName*/*actionName*/*propertyType*/`
+* `app/views/*controllerName*/*actionName*/`
+* `app/views/*controllerName*/*propertyName*/`
+* `app/views/*controllerName*/*propertyType*/`
+* `app/views/*controllerName*/`
+* `app/views/_fields/*class*/*propertyName*/`
+* `app/views/_fields/*superclass*/*propertyName*/`
+* `app/views/_fields/*associationType*/`
+* `app/views/_fields/*propertyType*/`
+* `app/views/_fields/*propertySuperclass*/`
+* `app/views/_fields/default/`
 
 The variables referenced in these paths are:
 
@@ -123,7 +123,7 @@ All class names are camel-cased simple forms. For example `java.lang.String` bec
 
 Templates are resolved in this order so that you can override in the more specific circumstance and fall back to successively more general defaults. For example, you can define a field template for all `java.lang.String` properties but override a specific property of a particular class to use more specialized rendering.
 
-Templates in plugins are resolved as well. This means plugins such as `Joda Time` can provide default rendering for special property types. A template in your application will take precedence over a template in a plugin at the same 'level'. For example if a plugin provides a `grails-app/views/_fields/string/_widget.gsp` the same template in your application will override it but if the plugin provides `grails-app/views/_fields/person/name/_widget.gsp` it would be used in preference to the more general template in your application.
+Templates in plugins are resolved as well. This means plugins such as `Joda Time` can provide default rendering for special property types. A template in your application will take precedence over a template in a plugin at the same 'level'. For example if a plugin provides a `app/views/_fields/string/_widget.gsp` the same template in your application will override it but if the plugin provides `app/views/_fields/person/name/_widget.gsp` it would be used in preference to the more general template in your application.
 
 For most properties the out-of-the-box defaults should provide a good starting point.
 
@@ -135,45 +135,45 @@ Imagine an object of class `Employee` that extends the class `Person` and has a
 
 You can override the template `f:field` uses with any of these:
 
-* `grails-app/views/*controllerName*/*actionName*/name/_themes/*themeName*/_wrapper.gsp`
-* `grails-app/views/*controllerName*/*actionName*/name/_wrapper.gsp`
-* `grails-app/views/*controllerName*/*actionName*/string/_wrapper.gsp`
-* `grails-app/views/*controllerName*/*actionName*/_wrapper.gsp`
-* `grails-app/views/*controllerName*/name/_wrapper.gsp`
-* `grails-app/views/*controllerName*/string/_wrapper.gsp`
-* `grails-app/views/*controllerName*/_wrapper.gsp`
-* `grails-app/views/_fields/employee/name/_wrapper.gsp`
-* `grails-app/views/_fields/person/name/_wrapper.gsp`
-* `grails-app/views/_fields/string/_wrapper.gsp`
-* `grails-app/views/_fields/default/_wrapper.gsp`
+* `app/views/*controllerName*/*actionName*/name/_themes/*themeName*/_wrapper.gsp`
+* `app/views/*controllerName*/*actionName*/name/_wrapper.gsp`
+* `app/views/*controllerName*/*actionName*/string/_wrapper.gsp`
+* `app/views/*controllerName*/*actionName*/_wrapper.gsp`
+* `app/views/*controllerName*/name/_wrapper.gsp`
+* `app/views/*controllerName*/string/_wrapper.gsp`
+* `app/views/*controllerName*/_wrapper.gsp`
+* `app/views/_fields/employee/name/_wrapper.gsp`
+* `app/views/_fields/person/name/_wrapper.gsp`
+* `app/views/_fields/string/_wrapper.gsp`
+* `app/views/_fields/default/_wrapper.gsp`
 
 override the template `f:widget` uses with any of these:
 
-* `grails-app/views/*controllerName*/*actionName*/name/_themes/*themeName*/_widget.gsp`
-* `grails-app/views/*controllerName*/*actionName*/name/_widget.gsp`
-* `grails-app/views/*controllerName*/*actionName*/string/_widget.gsp`
-* `grails-app/views/*controllerName*/*actionName*/_widget.gsp`
-* `grails-app/views/*controllerName*/name/_widget.gsp`
-* `grails-app/views/*controllerName*/string/_widget.gsp`
-* `grails-app/views/*controllerName*/_widget.gsp`
-* `grails-app/views/_fields/employee/name/_widget.gsp`
-* `grails-app/views/_fields/person/name/_widget.gsp`
-* `grails-app/views/_fields/string/_widget.gsp`
-* `grails-app/views/_fields/default/_widget.gsp`
+* `app/views/*controllerName*/*actionName*/name/_themes/*themeName*/_widget.gsp`
+* `app/views/*controllerName*/*actionName*/name/_widget.gsp`
+* `app/views/*controllerName*/*actionName*/string/_widget.gsp`
+* `app/views/*controllerName*/*actionName*/_widget.gsp`
+* `app/views/*controllerName*/name/_widget.gsp`
+* `app/views/*controllerName*/string/_widget.gsp`
+* `app/views/*controllerName*/_widget.gsp`
+* `app/views/_fields/employee/name/_widget.gsp`
+* `app/views/_fields/person/name/_widget.gsp`
+* `app/views/_fields/string/_widget.gsp`
+* `app/views/_fields/default/_widget.gsp`
 
 And override the template _f:display_ uses with any of these:
 
-* `grails-app/views/*controllerName*/*actionName*/name/_themes/*themeName*/_displayWrapper.gsp`
-* `grails-app/views/*controllerName*/*actionName*/name/_displayWrapper.gsp`
-* `grails-app/views/*controllerName*/*actionName*/string/_displayWrapper.gsp`
-* `grails-app/views/*controllerName*/*actionName*/_displayWrapper.gsp`
-* `grails-app/views/*controllerName*/name/_displayWrapper.gsp`
-* `grails-app/views/*controllerName*/string/_displayWrapper.gsp`
-* `grails-app/views/*controllerName*/_displayWrapper.gsp`
-* `grails-app/views/_fields/employee/name/_displayWrapper.gsp`
-* `grails-app/views/_fields/person/name/_displayWrapper.gsp`
-* `grails-app/views/_fields/string/_displayWrapper.gsp`
-* `grails-app/views/_fields/default/_displayWrapper.gsp`
+* `app/views/*controllerName*/*actionName*/name/_themes/*themeName*/_displayWrapper.gsp`
+* `app/views/*controllerName*/*actionName*/name/_displayWrapper.gsp`
+* `app/views/*controllerName*/*actionName*/string/_displayWrapper.gsp`
+* `app/views/*controllerName*/*actionName*/_displayWrapper.gsp`
+* `app/views/*controllerName*/name/_displayWrapper.gsp`
+* `app/views/*controllerName*/string/_displayWrapper.gsp`
+* `app/views/*controllerName*/_displayWrapper.gsp`
+* `app/views/_fields/employee/name/_displayWrapper.gsp`
+* `app/views/_fields/person/name/_displayWrapper.gsp`
+* `app/views/_fields/string/_displayWrapper.gsp`
+* `app/views/_fields/default/_displayWrapper.gsp`
 
 During template development it is usually recommended to disable template caching in order to allow the plugin to recognize new/renamed/moved templates without restarting the application. See the "Performance" section of the guide for the exact settings.
 
@@ -194,8 +194,7 @@ grails:
 ----
 
 
-=== Default Behaviour - Using Grails Widget Tags
-
+=== Default Behaviour - Using Grace Widget Tags
 
 If no template override is found the plugin will use the standard grails input tags (e.g. `g:select`, `g:checkbox`, `g:field`) for rendering input controls.
 Using `f:field` you can pass extra arguments (e.g. `optionKey`, `optionValue`) through to these tags by prefixing them with `widget-`, e.g.
@@ -208,7 +207,6 @@ Using `f:field` you can pass extra arguments (e.g. `optionKey`, `optionValue`) t
 
 === Template parameters
 
-
 The `f:field` and `f:widget` tags will pass the following parameters to your templates or to the body of `f:field` if you use one:
 
 .Template Parameters
@@ -276,7 +274,6 @@ NOTE: If the `bean` attribute was not supplied to `f:field` then `bean`, `type`,
 
 === Field labels
 
-
 If the `label` attribute is not supplied to the `f:field` tag then the label string passed to the field template is resolved by convention. The plugin uses the following order of preference for the label:
 
 * An i18n message using the key '_beanClass_._path_`.label`'. For example when using `<f:field bean="personInstance" property="address.city"/>` the plugin will try the i18n key `person.address.city.label`. If the property path contains any index it is removed so `<f:field bean="authorInstance" property="books<<0>>.title"/>` would use the key `author.books.title.label`.
@@ -286,7 +283,6 @@ If the `label` attribute is not supplied to the `f:field` tag then the label str
 
 === Locating Field Templates Directly
 
-
 Rather than relying on the convention described previously to locate the template(s) to be used for a particular field, it is
 instead possible to directly specify the directory containing the templates. This feature was introduced in version 1.5.
 
@@ -322,7 +318,6 @@ by convention.
 
 === Locating Templates Directly Example
 
-
 [source,groovy]
 ----
 // renders _fields/\_themes/bs-horizontal/custom/_wrapper.gsp:

…/main/docs/guide/embeddedProperties.adoc src/docs/guide/embeddedProperties.adocsrc/main/docs/guide/embeddedProperties.adoc renamed to src/docs/guide/embeddedProperties.adoc src/main/docs/guide/embeddedProperties.adoc renamed to src/docs/guide/embeddedProperties.adoc

@@ -12,6 +12,6 @@ Embedded properties are handled in a special way by the `f:field` and `f:all` ta
 </fieldset>
 ----
 
-You can customize how embedded properties are surrounded by providing a layout at `grails-app/views/layouts/_fields/embedded.gsp` which will override the default layout provided by the plugin.
+You can customize how embedded properties are surrounded by providing a layout at `app/views/layouts/_fields/embedded.gsp` which will override the default layout provided by the plugin.
 
 When you use the `f:all` tag it will automatically handle embedded properties in this way.

…s/guide/includingTemplatesInPlugins.adoc …s/guide/includingTemplatesInPlugins.adocsrc/main/docs/guide/includingTemplatesInPlugins.adoc renamed to src/docs/guide/includingTemplatesInPlugins.adoc src/main/docs/guide/includingTemplatesInPlugins.adoc renamed to src/docs/guide/includingTemplatesInPlugins.adoc

@@ -1,5 +1,5 @@
 == Including Templates in Plugins
 
-Plugins can include field and/or input level templates to support special UI rendering or non-standard property types. Just include the templates in the plugin's `grails-app/views` directory as described in the <<customizingFieldRendering,Customizing Field Rendering>> section.
+Plugins can include field and/or input level templates to support special UI rendering or non-standard property types. Just include the templates in the plugin's `app/views` directory as described in the <<customizingFieldRendering,Customizing Field Rendering>> section.
 
 WARNING: If you supply templates in a plugin you should consider declaring a `<%@page defaultCodec="html" %>` directive so that any HTML unsafe property values are escaped properly regardless of the default codec used by client apps.

src/main/docs/guide/index.adoc src/docs/guide/index.adocsrc/main/docs/guide/index.adoc renamed to src/docs/guide/index.adoc

@@ -53,7 +53,7 @@ include::ref/Tags/display.adoc[]
 include::ref/Tags/displayWidget.adoc[]
 
 [[ref-tags-field]]
-==== field
+== field
 
 include::ref/Tags/field.adoc[]
 

src/docs/guide/introduction.adoc

@@ -0,0 +1,13 @@
+== Introduction
+
+The _Fields plugin_ allows you to customize the rendering of input fields for properties of domain objects, command beans and POGOs based on their type, name, etc. The plugin aims to:
+
+* Use good defaults for fields.
+* Make it very easy to override the field rendering for particular properties or property types without having to replace entire form templates.
+* Not require you to copy and paste markup for containers, labels and error messages just because you need a different input type.
+* Support inputs for property paths of arbitrary depth and with indexing.
+* Enable other plugins to provide field rendering for special property types that gets picked up automatically (e.g. the _Joda Time_ plugin can provide templates for the various date/time types).
+* Support embedded properties of _GORM_ domain classes.
+
+== Changelog
+

src/main/docs/guide/links.yml src/docs/guide/links.ymlsrc/main/docs/guide/links.yml renamed to src/docs/guide/links.yml

@@ -1,12 +1,12 @@
 Scaffolding templates based on the _Fields_ plugin are quite powerful as they will pick up field and input rendering templates from your application and any plugins that provide them. This means that the useful life of scaffolding templates should be much longer as you do not need to replace the entire _create.gsp_ and/or _edit.gsp_ template just because you want to do something different with a certain property of one particular class.
 
-The plugin makes the _renderEditor.template_ file used by standard Grails scaffolding redundant. This template was very limited because it could not be extended by plugins or applications (only replaced) and was unable to support embedded properties of domain classes.
+The plugin makes the _renderEditor.template_ file used by standard Grace scaffolding redundant. This template was very limited because it could not be extended by plugins or applications (only replaced) and was unable to support embedded properties of domain classes.
 
 The _Fields_ plugin includes scaffolding templates you can use in your application by running:
 
 [source,groovy]
 ----
-grails install-form-fields-templates
+grace install-form-fields-templates
 ----
 
 This will overwrite any _create.gsp_ and _edit.gsp_ files you have in `src/templates/scaffolding`.