Add documentation: user guide and api docs

Closes gh-1081

Author: rainboyan

build.gradle

@@ -422,7 +422,7 @@ subprojects.each {
 }
 
 apply {
-    from 'gradle/docs.gradle' // tasks for building the documentation (e.g. user guide, javadocs)
+    // from 'gradle/docs.gradle' // tasks for building the documentation (e.g. user guide, javadocs)
     from 'gradle/assemble.gradle' // tasks for creating an installation or distribution
     from 'gradle/findbugs.gradle'
 }

docs/build.gradle

@@ -0,0 +1,80 @@
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+    dependencies {
+        classpath "org.graceframework:grace-gradle-plugin:2023.3.0-RC2"
+    }
+}
+
+apply plugin: 'groovy'
+apply plugin: 'java-library'
+apply plugin: 'org.graceframework.grace-doc'
+
+def DOCUMENTATION_GROUP = 'Documentation'
+def groovyVersion = libs.versions.groovy.get()
+def springFrameworkVersion = libs.versions.spring.framework.get()
+def springBootVersion = libs.versions.spring.boot.get()
+
+repositories {
+    mavenCentral()
+}
+
+configurations {
+    documentation
+}
+
+dependencies {
+    documentation libs.groovy.ant
+    documentation libs.groovy.groovydoc
+    documentation libs.javaparser
+    documentation libs.spring.core
+    documentation libs.spring.boot
+    documentation libs.snakeyaml
+}
+
+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_GROUP
+    docTitle = "Grace Framework - ${project.version}"
+    windowTitle = "Grace Framework - ${project.version}"
+    footer = ""
+    destinationDir = project.file('build/docs/manual/api')
+    def files = []
+    project.rootProject.subprojects
+            .findAll { !it.name != 'docs' && !it.name.startsWith('grace-test-suite') }
+            .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
+
+    link("https://docs.oracle.com/en/java/javase/17/docs/api/", 'java.')
+    link("https://docs.groovy-lang.org/docs/groovy-${groovyVersion}/html/gapi/", 'groovy.', 'org.codehaus.groovy.', 'org.apache.groovy.')
+    link("https://docs.spring.io/spring-framework/docs/${springFrameworkVersion}/javadoc-api", 'org.springframework.core.', 'org.springframework.context.', 'org.springframework.beans.')
+    link("https://docs.spring.io/spring-boot/${springBootVersion[0..2]}/api/java", 'org.springframework.boot.', 'org.springframework.boot.actuate.info.')
+}
+
+docs {
+    dependsOn groovydoc
+    sourceDir = project.file('src/docs')
+}

docs/src/docs/guide/gettingStarted.adoc

@@ -0,0 +1,71 @@
+Next, let's get started on creating your first project.
+
+[source,console,subs="attributes"]
+----
+$ sdk use grace {version}
+$ grace create-app com.examples.bookstore
+----
+
+you will see the new project has been created,
+
+[source,console,subs="attributes"]
+----
+| Creating a new application
+
+     Name:          bookstore
+     Package:       com.example
+     Profile:       web
+     Features:      asset-pipeline, async, bootstrap, cache, database-migration, events, fields, geb, gsp, hibernate, jquery, scaffolding
+     Database:      h2
+     Project root:  /Users/grace/bookstore
+
+| Application created by Grace {version}.
+----
+
+[source,console]
+----
+.
+├── app
+│   ├── assets
+│   ├── conf
+│   ├── controllers
+│   ├── domain
+│   ├── i18n
+│   ├── init
+│   ├── services
+│   ├── taglib
+│   └── views
+├── buildSrc
+│   └── build.gradle
+├── db
+│   └── migrations
+├── gradle
+│   └── wrapper
+├── src
+│   ├── integration-test
+│   ├── main
+│   └── test
+├── HELP.md
+├── README.md
+├── build.gradle
+├── gradle.properties
+├── gradlew
+├── gradlew.bat
+└── settings.gradle
+----
+
+then we create a domain class `Book`, which has a `name` property,
+We use `generate` command to generate all the controller, services, gsp views,
+
+[source,console,subs="attributes"]
+----
+$ cd blog
+$ grace generate scaffold Book name:string
+----
+
+Now, let's running the app,
+
+[source,console,subs="attributes"]
+----
+$ grace run-app
+----

docs/src/docs/guide/installation.adoc

@@ -0,0 +1,46 @@
+Please follow these instructions in order to complete your installation.
+
+=== Prerequisites
+
+Grace CLI requires Java JDK v17.0 or above in order to run. Groovy v4.0.x is packaged as part of this distribution, and therefore does not need to be installed (any
+existing Groovy installation is ignored).
+
+Grace CLI will use whatever JDK it finds on your path, to check that you have an appropriate version you should run:
+
+[source,console]
+----
+$ java -version
+----
+
+Alternatively, you can set the JAVA_HOME environment variable to point a suitable JDK.
+
+=== Environment Variables
+
+No specific environment variables are required to run the CLI, however, you may want to set GRACE_HOME to point to a specific installation. You should also add GRACE_HOME/bin to your PATH environment variable.
+
+=== Checking Your Installation
+
+To test if you have successfully installed the CLI you can run the following command:
+
+[source,console]
+----
+$ grace -v
+----
+
+If you see the output like below, congratulations, you have installed it successfully.
+
+[source,console]
+----
+------------------------------------------------------------
+Grace {version}
+------------------------------------------------------------
+
+Build time:   2025-06-22 13:30:19 UTC
+Revision:     ba9b75634a9c2e79e0612d93df9c9fc81d05dd74
+
+Spring Boot:  3.3.13
+Gradle:       8.14.2
+Groovy:       4.0.27
+JVM:          17.0.15 (BellSoft 17.0.15+10-LTS)
+OS:           Mac OS X 12.7.6 aarch64
+----

docs/src/docs/guide/introduction.adoc

@@ -0,0 +1,28 @@
+
+https://github.com/graceframework/grace-framework[Grace] is a fork of https://github.com/apache/grails-core/tree/5.1.x[Grails 5.1.x] that started development in early 2022, it's a powerful and open-source One-Person web framework used to build enterprise-grade https://spring.io/projects/spring-boot/[Spring Boot] applications with the powerful https://groovy-lang.org/[Groovy] programming language. The core framework is very extensible and there are numerous https://github.com/grace-plugins/[Plugins] available that provide easy integration of add-on features.
+
+=== Why Grace?
+
+Grace inherits the excellent concepts and designs of Grails, and based on this, has undergone significant restructuring to ensure that each module is independent and decoupled, such as Grace API, Grace Boot, Grace CLI, Grace Plugin API, Grace Plugin Core, Grace Spring Boot, Grace Util. Meanwhile, in order to better focus on maintenance and upgrades, Grace also merged the previously spun-off modules, Converters plugin, GSP, Grace Test Support. Grace Boot as an https://graceframework.org/grace-framework/2023.3.x/api/grails/boot/config/GrailsAutoConfiguration.html[Auto-configuration], it will load all other modules and plugins. Grace follows good modular design, and these modules can be used independently in Spring Boot applications.
+
+Spring is the foundation for Grace, which is built on top of Spring Boot. To better support Spring Boot and integrate with other Spring ecosystems, Grace has rewritten `Plugin.doWithSpring()` using Spring Boot's https://docs.spring.io/spring-boot/3.3/reference/using/auto-configuration.html[Auto-configuration], which also reduces redundant configurations and provides significant performance improvements. Grace has also provided https://docs.spring.io/spring-boot/3.3/specification/configuration-metadata/index.html[Configuration Metadata] files include in Grace plugins' jars, the files are designed to let IDE developers offer contextual help and “code completion” as users are working with application.properties or application.yaml files. So, a Grace plugin is an extended Spring Boot Starter.
+
+It is worth mentioning that Grace supports all current versions of Spring Boot, including https://github.com/graceframework/grace-framework/releases/tag/v2022.2.9[2.7], https://github.com/graceframework/grace-framework/releases/tag/v2023.0.3[3.0], https://github.com/graceframework/grace-framework/releases/tag/v2023.1.0[3.1], https://github.com/graceframework/grace-framework/releases/tag/v2023.2.0[3.2], https://github.com/graceframework/grace-framework/releases/tag/v2023.3.0[3.3], https://github.com/graceframework/grace-framework/releases/tag/v2023.3.0[3.4], and  https://github.com/graceframework/grace-framework/releases/tag/v2023.3.0[3.5]. This makes the upgrade path easier and more manageable.
+
+Grace has been actively developing, bringing numerous improvements and new features, including Plugins, GSP, Console, Shell, and https://github.com/grace-profiles[Profiles]. Of course, it has also fixed a large number of legacy defects left in Grails 5, this makes developers happy.
+
+You can learn more on the page https://github.com/graceframework/grace-framework/wiki/What's-New-in-Grace-Framework[What's New in Grace Framework].
+
+=== Grace vs Spring Boot
+
+Grace and Spring Boot frameworks are excellent for building web applications, but their use depends on what you want. Generally, Grace framework may be advantageous in full-stack and monolithic applications, but Spring Boot is preferred for developing complex and microservice applications.
+
+Grace is not a replacement for Spring Boot, it is built on top of Spring Boot. It provides its' own https://docs.spring.io/spring-boot/3.3/reference/features/developing-auto-configuration.html#features.developing-auto-configuration.custom-starter[Spring Boot Starters] - Grace Boot as an AutoConfiguration, it will load all other modules and plugins. Grace follows good modular design, and these modules can be used independently in Spring Boot applications. So, a Grace application is really a Spring Boot application.
+
+Grace has better developer productivity than Spring Boot. Because it follows the convention over the configuration principle, it minimizes code requirements. This enhances productivity and fosters faster app development. The framework creates faster and more functional prototypes than Spring Boot due to its simple code generation like scaffolding and CoC.
+
+Grace has better support Groovy than Spring Boot. Grace fully embraces Groovy to enable many features that would not be possible using Java alone, including flexible and powerful Plug-in architecture and a rich https://github.com/grace-plugins[Plugin ecosystem] and many built-in https://github.com/grace-plugins/grace-dynamic-modules[Dynamic Module types], many https://docs.groovy-lang.org/latest/html/documentation/#_domain_specific_languages[DSLs], https://docs.groovy-lang.org/latest/html/documentation/#_available_ast_transformations[AST Transformations], https://docs.groovy-lang.org/latest/html/documentation/#_traits[Trait]-based solutions, and much more.
+
+Grace provides a powerful CLI that allows you to quickly create new projects of many different types using https://github.com/grace-profiles[Application Profiles] and https://github.com/grace-templates[Templates] and get started easily. These are all extensible and easy to customize, you can create your own Profiles, Templates, and Commands to meet any of your needs. The learning curve for Grace is moderate and more straightforward than Spring Boot due to its emphasis on convention and simplicity.
+
+You can learn more on the page https://github.com/graceframework/grace-framework/wiki/Grace-vs-Spring-Boot[Grace vs Spring Boot].