From 44903f1c64d285c1a51c17d0ee1b6165700e563c Mon Sep 17 00:00:00 2001 From: Marcos Pereira Date: Fri, 12 Apr 2024 02:28:51 -0400 Subject: [PATCH] docs: Add new docs page for Gradle Plugin (#346) * docs: Add new docs page for Gradle Plugin * docs: correct defaults for gradle * docs(gradle): spelling and grammar improvements Co-authored-by: Niklas Keller --------- Co-authored-by: Niklas Keller --- docs/gradle-plugin.md | 270 ++++++++++++++++++++++++++++++++++++++++++ docs/jte-models.md | 37 +----- docs/maven-plugin.md | 6 +- docs/pre-compiling.md | 14 +-- mkdocs.yml | 1 + 5 files changed, 285 insertions(+), 43 deletions(-) create mode 100644 docs/gradle-plugin.md diff --git a/docs/gradle-plugin.md b/docs/gradle-plugin.md new file mode 100644 index 00000000..283510d5 --- /dev/null +++ b/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` property 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, but does not compile them to `.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 \ No newline at end of file diff --git a/docs/jte-models.md b/docs/jte-models.md index c7b5e09e..865a3f38 100644 --- a/docs/jte-models.md +++ b/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 diff --git a/docs/maven-plugin.md b/docs/maven-plugin.md index c83ee611..8dda5d4e 100644 --- a/docs/maven-plugin.md +++ b/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 } diff --git a/docs/pre-compiling.md b/docs/pre-compiling.md index afaee027..9199f9c9 100644 --- a/docs/pre-compiling.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 1066c035..1b3c87d3 100644 --- a/mkdocs.yml +++ b/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