docs: Add new docs page for Gradle Plugin

docs/gradle-plugin.md

@@ -0,0 +1,270 @@
+---
+title: Gradle Plugin
+description: How to use the jte Gradle plugin.
+---
+
+jte provides a [Gradle Plugin][jte-gradle-plugin] that you can integrate in your build process to either [precompile templates](pre-compiling.md), or to generate the Java/Kotlin code for your templates.
+
+
+!!! tip "Versions alignment"
+
+    Make sure the jte gradle plugin version matches the jte dependency version. You can create a `jteVersion` in `gradle.properties` to sync the versions easily.
+
+The plugin provides two tasks:
+
+## `precompileJte` task { #precompile-task }
+
+See [Precompiling Templates](pre-compiling.md) for more information. To use and configure this task, you would use:
+
+=== "Groovy"
+
+    ```groovy linenums="1"
+    plugins {
+        id 'java'
+        id 'gg.jte.gradle' version '${jteVersion}'
+    }
+
+    dependencies {
+        implementation('gg.jte:jte:${jteVersion}')
+    }
+
+    jte {
+        precompile()
+    }
+    ```
+
+=== "Kotlin"
+
+    ```kotlin linenums="1"
+    plugins {
+        java
+        id("gg.jte.gradle") version("${jteVersion}")
+    }
+
+    dependencies {
+        implementation("gg.jte:jte:${jteVersion}")
+    }
+
+    jte {
+        precompile()
+    }
+    ```
+
+### Task inputs { #precompile-inputs }
+
+The follow inputs will be picked by the `precompileJte` task:
+
+| Parameter               | Description                                                                       | Default                                                        |
+|-------------------------|-----------------------------------------------------------------------------------|----------------------------------------------------------------|
+| `sourceDirectory`       | The directory where template files are located                                    | `src/main/jte`                                                 |
+| `targetDirectory`       | The directory where compiled classes should be written to                         | `jte-classes`                                                  |
+| `compilePath`           | The compile-classpath to use                                                      | `sourceSets.main.runtimeClasspath`                             |
+| `contentType`           | The content type of all templates. Either `Plain` or `Html`                       | `Html`                                                         |
+| `trimControlStructures` | Trims control structures, resulting in prettier output                            | `false`                                                        |
+| `htmlTags`              | Intercepts the given html tags during template compilation                        | None                                                           |
+| `htmlPolicyClass`       | An [`HtmlPolicy`][html-policy] used to check the parsed HTML at compile time      | None                                                           |
+| `htmlCommentsPreserved` | If HTML comments should be preserved in the output                                | `false`                                                        |
+| `binaryStaticContent`   | If to generate a [binary content](binary-rendering.md) resource for each template | `false`                                                        |
+| `compileArgs`           | Sets additional compiler arguments for `jte` templates.                           | None                                                           |
+| `kotlinCompileArgs`     | Sets additional compiler arguments for `kte` templates                            | None                                                           |
+| `packageName`           | The package name, where template classes are generated to                         | [`Constants.PACKAGE_NAME_PRECOMPILED`][constants-package-name] |
+
+!!! info "About `htmlPolicyClass`"
+
+    The `htmlPolicyClass` will default to `gg.jte.html.OwaspHtmlPolicy` if the content type is `Html`.
+
+!!! warning "Clean all before precompiling"
+
+    The `precompileJte` task cleans the directory containing the compiled template classes every time it runs. In your local development environment, it may make more sense to use [hot reloading](hot-reloading.md).
+
+## `generateJte` task { #generate-task }
+
+This task generates all template classes in a sources directory. This only generates `.java`/`.kt` files, not `.class` files.
+
+=== "Groovy"
+
+    ```groovy linenums="1"
+    plugins {
+        id 'java'
+        id 'gg.jte.gradle' version '${jte.version}'
+    }
+
+    dependencies {
+        implementation('gg.jte:jte:${jte.version}')
+    }
+
+    jte {
+        generate()
+    }
+    ```
+
+=== "Kotlin"
+
+    ```kotlin linenums="1"
+    plugins {
+        java
+        id("gg.jte.gradle") version("${jte.version}")
+    }
+
+    dependencies {
+        implementation("gg.jte:jte:${jte.version}")
+    }
+
+    jte {
+        generate()
+    }
+    ```
+
+### Task Inputs { #generate-inputs }
+
+The follow inputs will be picked by the `generateJte` task:
+
+| Parameter                 | Description                                                                       | Default                                                        |
+|---------------------------|-----------------------------------------------------------------------------------|----------------------------------------------------------------|
+| `sourceDirectory`         | The directory where template files are located                                    | `src/main/jte`                                                 |
+| `targetDirectory`         | Destination directory to store generated templates.                               | `${project.build.directory}/generated-sources/jte`             |
+| `contentType`             | The content type of all templates. Either `Plain` or `Html`                       | `Html`                                                         |
+| `trimControlStructures`   | Trims control structures, resulting in prettier output                            | `false`                                                        |
+| `htmlTags`                | Intercepts the given html tags during template compilation                        | None                                                           |
+| `htmlCommentsPreserved`   | If HTML comments should be preserved in the output                                | `false`                                                        |
+| `binaryStaticContent`     | If to generate a [binary content](binary-rendering.md) resource for each template | `false`                                                        |
+| `packageName`             | The package name, where template classes are generated to                         | [`Constants.PACKAGE_NAME_PRECOMPILED`][constants-package-name] |
+| `targetResourceDirectory` | Directory in which to generate non-java files (resources)                         | None                                                           |
+
+### Extensions { #generate-extensions }
+
+Currently, the following extensions exist:
+
+#### `gg.jte.models.generator.ModelExtension` { #model-extension }
+
+See details about it in the [jte-models documentation](jte-models.md).
+
+##### Properties { #model-extension-properties }
+
+The following parameters are available for this extension:
+
+| Parameter                  | Description                                                               | Default |
+|----------------------------|---------------------------------------------------------------------------|---------|
+| `interfaceAnnotation`      | The FQCN of the annotation to add to the generated interface              | None    |
+| `implementationAnnotation` | The FQCN of the annotation to add to the generated implementation classes | None    |
+| `language`                 | The target language for the generated classes. Either `Java` or `Kotlin`  | `Java`  |
+| `includePattern`           | A regular expression to only include certain templates                    | None    |
+| `excludePattern`           | A regular expression to exclude certain templates                         | None    |
+
+##### Example { #model-extension-example }
+
+=== "Gradle (Groovy DSL)"
+
+    ```groovy linenums="1"
+    plugins {
+        id 'gg.jte.gradle' version '${jte.version}'
+    }
+
+    dependencies {
+        implementation 'gg.jte:jte-runtime:${jte.version}'
+        jteGenerate 'gg.jte:jte-models:${jte.version}'
+    }
+
+    jte {
+        generate()
+
+        // Remove the properties that don't make sense to your project
+        jteExtension('gg.jte.models.generator.ModelExtension') {
+            // Target language ("Java" and "Kotlin" are supported). "Java" is the default.
+            language = 'Java'
+
+            // Annotations to add to generated interfaces and classes
+            interfaceAnnotation = '@foo.bar.MyAnnotation'
+            implementationAnnotation = '@foo.bar.MyAnnotation'
+
+            // Patterns to include (or exclude) certain templates
+            includePattern = '\.pages\..*'
+            excludePattern = '\.components\..*'
+        }
+    }
+    ```
+
+=== "Gradle (Kotlin DSL)"
+
+    ```kotlin linenums="1"
+    plugins {
+        id("gg.jte.gradle") version "${jte.version}"
+    }
+
+    dependencies {
+        implementation("gg.jte:jte-runtime:${jte.version}")
+        jteGenerate("gg.jte:jte-models:${jte.version}")
+    }
+
+    jte {
+        generate()
+
+        // Remove the properties that don't make sense to your project
+        jteExtension("gg.jte.models.generator.ModelExtension") {
+            // Target language ("Java" and "Kotlin" are supported). "Java" is the default.
+            property("language", "Java")
+
+            // Annotations to add to generated interfaces and classes
+            property("interfaceAnnotation", "@foo.bar.MyAnnotation")
+            property("implementationAnnotation", "@foo.bar.MyAnnotation")
+
+            // Patterns to include (or exclude) certain templates
+            property("includePattern", "\.pages\..*")
+            property("excludePattern", '\.components\..*")
+        }
+    }
+    ```
+
+#### `gg.jte.nativeimage.NativeResourcesExtension` { #native-resources-extension }
+
+!!! info "Version note"
+
+    Available since jte ^^**1.10.0**^^.
+
+An application jar with generated classes can be built into a native binary using [GraalVM native-image](https://www.graalvm.org/reference-manual/native-image/). To support this, this extension generates the necessary configuration files to tell `native-image` about classes loaded by reflection.
+
+##### Example { #native-resources-extension-example }
+
+=== "Gradle (Groovy DSL)"
+
+    ```groovy linenums="1"
+    plugins {
+        id 'gg.jte.gradle' version '${jte.version}'
+    }
+
+    dependencies {
+        implementation 'gg.jte:jte-runtime:${jte.version}'
+        jteGenerate 'gg.jte:jte-models:${jte.version}'
+    }
+
+    jte {
+        generate()
+        jteExtension('gg.jte.nativeimage.NativeResourcesExtension')
+    }
+    ```
+
+=== "Gradle (Kotlin DSL)"
+
+    ```kotlin linenums="1"
+    plugins {
+        id("gg.jte.gradle") version "${jte.version}"
+    }
+
+    dependencies {
+        implementation("gg.jte:jte-runtime:${jte.version}")
+        jteGenerate("gg.jte:jte-models:${jte.version}")
+    }
+
+    jte {
+        generate()
+        jteExtension("gg.jte.nativeimage.NativeResourcesExtension")
+    }
+    ```
+
+!!! tip "Sample project"
+
+    There's an example [Gradle test project](https://github.com/casid/jte/blob/{{ latest-git-tag }}/test/jte-runtime-cp-test-gradle-convention/build.gradle) using `native-image` compilation.
+
+[jte-gradle-plugin]: https://plugins.gradle.org/plugin/gg.jte.gradle
+[html-policy]: https://www.javadoc.io/doc/gg.jte/jte-runtime/{{ latest-git-tag }}/gg.jte.runtime/gg/jte/html/HtmlPolicy.html
+[constants-package-name]: https://www.javadoc.io/doc/gg.jte/jte-runtime/{{ latest-git-tag }}/gg/jte.runtime/gg/jte/Constants.html#PACKAGE_NAME_PRECOMPILED

docs/jte-models.md

@@ -61,21 +61,6 @@ To use jte-models, set up your build script to include one of these:
         generate()
         binaryStaticContent = true
         jteExtension 'gg.jte.models.generator.ModelExtension'
-        // or to configure the generator
-        /*
-        jteExtension('gg.jte.models.generator.ModelExtension') {
-            // Target language ("Java" and "Kotlin" are supported). "Java" is the default.
-            language = 'Java'
-
-            // Annotations to add to generated interfaces and classes
-            interfaceAnnotation = '@foo.bar.MyAnnotation'
-            implementationAnnotation = '@foo.bar.MyAnnotation'
-
-            // Patterns to include (or exclude) certain templates
-            includePattern = '\.pages\..*'
-            excludePattern = '\.components\..*'
-        }
-         */
     }
     ```
 
@@ -95,29 +80,17 @@ To use jte-models, set up your build script to include one of these:
         generate()
         binaryStaticContent.set(true)
         jteExtension("gg.jte.models.generator.ModelExtension")
-        // or to configure the generator:
-        /*
-        jteExtension("gg.jte.models.generator.ModelExtension") {
-            // Target language ("Java" and "Kotlin" are supported). "Java" is the default.
-            property("language", "Java")
-
-            // Annotations to add to generated interfaces and classes
-            property("interfaceAnnotation", "@foo.bar.MyAnnotation")
-            property("implementationAnnotation", "@foo.bar.MyAnnotation")
-
-            // Patterns to include (or exclude) certain templates
-            property("includePattern", "\.pages\..*")
-            property("excludePattern", '\.components\..*")
-        }
-         */
     }
     ```
 
 Run the build to generate classes.
 
-!!! tip "Maven configuration"
+!!! info "Full configuration"
+
+    See details about how to fully configure the extension:
 
-    See details about how to fully configure the extension in the [Maven plugin documentation](maven-plugin.md#model-extension).
+    - [Maven plugin documentation](maven-plugin.md#model-extension)
+    - [Gradle plugin documentation](gradle-plugin.md#model-extension)
 
 ## Output
 

docs/maven-plugin.md

@@ -188,7 +188,11 @@ The following parameters are available for this extension:
 
 #### `gg.jte.nativeimage.NativeResourcesExtension` { #native-resources-extension }
 
-See details about it in the [native-image documentation](pre-compiling.md#graalvm-native-image-support). This extension requires no parameters.
+!!! info "Version note"
+
+    Available since jte ^^**1.10.0**^^.
+
+An application jar with generated classes can be built into a native binary using [GraalVM native-image](https://www.graalvm.org/reference-manual/native-image/). To support this, this extension generates the necessary configuration files to tell `native-image` about classes loaded by reflection.
 
 ##### Example { #native-resources-extension-example }
 

docs/pre-compiling.md

@@ -225,23 +225,17 @@ The [Gradle plugin][jte-gradle-plugin] can generate all templates during the Gra
 
     jte {
         generate()
-        generate()
     }
     ```
 
 ## GraalVM native-image support { #graalvm-native-image-support }
 
-!!! info "Version note"
-
-    Available since jte ^^**1.10.0**^^.
-
-An application jar with generated classes can be built into a native binary using [GraalVM native-image](https://www.graalvm.org/reference-manual/native-image/). To support this, jte can generate the necessary configuration files to tell `native-image` about classes loaded by reflection.
-
-To see how to use this feature in a Maven project, check out the [Maven plugin documentation](maven-plugin.md#native-resources-extension).
+!!! info "How to use"
 
-To use this feature, set `#!groovy jteExtension("gg.jte.nativeimage.NativeResourcesExtension")` in your Gradle `jte` block. 
+    See details about how to configure your build tool to generate the necessary configuration files to tell `native-image` about classes loaded by reflection:
 
-There's an example [Gradle test project](https://github.com/casid/jte/blob/{{ latest-git-tag }}/test/jte-runtime-cp-test-gradle-convention/build.gradle) using `native-image` compilation.
+    - [Maven plugin documentation](maven-plugin.md#native-resources-extension)
+    - [Gradle plugin documentation](gradle-plugin.md#native-resources-extension)
 
 ## Binary encoding
 

mkdocs.yml

@@ -79,6 +79,7 @@ nav:
     - "HTML Rendering": html-rendering.md
   - "Build Tools":
     - "Maven Plugin": maven-plugin.md
+    - "Gradle Plugin": gradle-plugin.md
   - "How To":
     - "Hot Reloading": hot-reloading.md
     - "Precompiling Templates": pre-compiling.md