Rework docs to all be PublishGuide compatible & remove duplicated, deprecated source files

Author: jdaugherty

etc/layout/style/layout.html

@@ -23,7 +23,7 @@
         <% if (logo) { %>
         <span id="logo">${logo}</span>
         <% } %>
-        Groovy Server Pages
+        ${title.encodeAsHtml()}
     </div>
     <div class="navLinks">
         <ul>

fields/README.md

@@ -7,8 +7,8 @@ logic.
 
 ## Documentation
 
-* Latest Guide - https://views.grails.org/latest/fields/guide
+* Latest Guide - https://views.grails.org/latest/fields
 * Latest API - https://views.grails.org/latest/fields/api
 
-* Snapshot Guide - https://views.grails.org/snapshot/fields/guide
+* Snapshot Guide - https://views.grails.org/snapshot/fields
 * Snapshot API - https://views.grails.org/snapshot/fields/api

fields/docs/build.gradle

@@ -2,12 +2,9 @@ ext {
     guideTitle = 'Grails Fields Plugin'
     guideSubtitle = 'Grails Fields Plugin - customize the rendering of input fields for Grails artifacts'
 
-    apiDocsProjects = [
-            'fields': [
-                    docTitle   : 'Grails Fields Plugin - ' + projectVersion,
-                    windowTitle: 'fields ' + projectVersion + ' API'
-            ]
-    ]
+    apiDocsProjects = ['fields-plugin']
+    apiDocTitle = "Grails Fields Plugin API - ${projectVersion}"
+    apiWindowTitle = "Grails Fields Plugin API - ${projectVersion}"
 
     asciidoctorAttributes = [
             copyright           : 'Apache License, Version 2.0',

fields/docs/src/docs/changelog.adoc fields/docs/src/docs/guide/changelog.adoc

@@ -1,5 +1,3 @@
-== Changelog
-
 === Version 5.0.0 - Grails 5.3.x
 
 In your `build.gradle` file, use:

fields/docs/src/docs/customizingFieldRendering.adoc fields/docs/src/docs/guide/customizingFieldRendering.adoc

@@ -1,5 +1,3 @@
-== Customizing Field Rendering
-
 The plugin resolves the GSP template used for each property according to conventions. You can override the rendering based
 on the class and property name or the property type. The `f:field` tag looks for a template called `_wrapper.gsp`, the `f:widget`
 tag looks for a template called `_widget.gsp`, the `f:display` tag looks for a template called `_displayWrapper.gsp`.

fields/docs/src/docs/embeddedProperties.adoc fields/docs/src/docs/guide/embeddedProperties.adoc

@@ -1,5 +1,3 @@
-== Embedded Properties
-
 Embedded properties are handled in a special way by the `f:field` and `f:all` tags. If the `property` attribute you pass to `f:field` is an embedded property then the tag recursively renders each individual property of the embedded class with a surrounding `fieldset`. For example if you have a `Person` class with a `name` property and an `Address` embedded class with `street`, `city` and `country` properties `<f:field bean="person" property="address">` will effectively do this:
 
 [source,groovy]

fields/docs/src/docs/guide/includingTemplatesInPlugins.adoc

@@ -0,0 +1,9 @@
+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.
+
+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.
+
+In order to be performant, the Fields plugin caches field template lookup results by default. This makes it possible to perform the time-consuming template path resolutions only once during the runtime of the application.
+
+When template caching is active, only the first page renderings are slow, subsequent ones are fast.
+
+Due to the flexibility needed during template development, this feature can be disabled so it would be possible to recognize newly added field templates without restarting the application. As a result, with bigger webpages, containing a lot of fields, rendering may be fairly slow in development (depending on the number of fields on the page).

fields/docs/src/docs/guide/index.adoc

@@ -0,0 +1,28 @@
+= Fields Plugin
+
+[#introduction]
+include::introduction.adoc[]
+
+[#installation]
+include::installation.adoc[]
+
+[#usage]
+include::usage.adoc[]
+
+[#customizingFieldRendering]
+include::customizingFieldRendering.adoc[]
+
+[#embeddedProperties]
+include::embeddedProperties.adoc[]
+
+[#themes]
+include::themes.adoc[]
+
+[#includingTemplatesInPlugins]
+include::includingTemplatesInPlugins.adoc[]
+
+[#performance]
+include::performance.adoc[]
+
+[#changelog]
+include::changelog.adoc[]

fields/docs/src/docs/installation.adoc fields/docs/src/docs/guide/installation.adoc

@@ -1,4 +1,3 @@
-== Installation
 The plugin is available on Maven Central and should be a dependency like this:
 
 [source,groovy,subs="attributes"]

fields/docs/src/docs/introduction.adoc fields/docs/src/docs/guide/introduction.adoc

@@ -1,5 +1,3 @@
-== 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.

fields/docs/src/docs/guide/performance.adoc

@@ -0,0 +1,22 @@
+For template development, the following configuration attribute should be placed in the development environment section of your application's Config.groovy:
+
+.application.groovy
+[source,groovy]
+----
+grails.plugin.fields.disableLookupCache = true
+----
+
+or
+
+.application.yml
+[source,yml]
+----
+environments:
+    development:
+        grails:
+            plugin:
+                fields:
+                    disableLookupCache: true
+----
+
+After the template development has finished, it is recommended to re-enable the template lookup cache in order to have a performant page rendering even during development.

fields/docs/src/docs/scaffolding.adoc fields/docs/src/docs/guide/scaffolding.adoc

@@ -1,5 +1,3 @@
-== Themes
-
 Since version 2.1.4 It is possible to create themes to provide set of templates for different css frameworks or form layouts.
 For example, a bootstrap-fields plugin can provide different themes (eg bs-horizontal, bs-vertical) to support horizontal and vertical form layouts. And another plugin can provide theme for purecss framework.
 

fields/docs/src/docs/scaffolding/definitions/index.adoc fields/docs/src/docs/guide/scaffolding/definitions/index.adoc

@@ -1,7 +1,9 @@
 introduction: Introduction
+installation: Installation
 usage: Usage
 customizingFieldRendering: Customizing Field Rendering
 embeddedProperties: Embedded Properties
 themes: Themes
 includingTemplatesInPlugins: Including Templates in Plugins
 performance: Performance
+changeLog: Change Log

fields/docs/src/docs/scaffolding/extending/index.adoc fields/docs/src/docs/guide/scaffolding/extending/index.adoc

@@ -1,5 +1,3 @@
-== Usage
-
 The plugin provides a set of tags you can use to render the fields in a form.
 
 In the simplest case you can use `f:all` to render a field for every property of a bean (the domain object or command the form will bind to):