feat(gherkin-to-asciidoc): write report snippets and support custom Mustache templates

.github/workflows/example-gherkin-to-asciidoc-snippet-templates-build.yml

@@ -0,0 +1,38 @@
+name: Example - Gherkin to AsciiDoc Snippet Templates Build
+on:
+  push:
+    paths:
+      - 'examples/gherkin-to-asciidoc/snippet-templates/**/*.feature'
+      - 'examples/gherkin-to-asciidoc/snippet-templates/**/*.java'
+      - 'examples/gherkin-to-asciidoc/snippet-templates/**/*.mustache'
+      - 'examples/gherkin-to-asciidoc/snippet-templates/**/*.gradle'
+      - 'examples/gherkin-to-asciidoc/snippet-templates/**/*.properties'
+      - 'examples/gherkin-to-asciidoc/snippet-templates/**/libs.versions.toml'
+      - '.github/workflows/example-gherkin-to-asciidoc-snippet-templates-build.yml'
+
+jobs:
+  Build-Example:
+    name: Build Example
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Setup Java
+        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # v5.3.0
+        with:
+          distribution: 'temurin'
+          java-version: 21
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0
+
+      - name: Build example
+        run: |
+          cd examples/gherkin-to-asciidoc/snippet-templates
+          chmod +x ./gradlew
+          ./gradlew generateAllReports build --no-daemon

examples/README.adoc

@@ -33,3 +33,5 @@ include::jacoco-exclusion-report/dsl/README.adoc[leveloffset=+1]
 include::gherkin-to-asciidoc/plain/README.adoc[leveloffset=+1]
 
 include::gherkin-to-asciidoc/progress-tracking/README.adoc[leveloffset=+1]
+
+include::gherkin-to-asciidoc/snippet-templates/README.adoc[leveloffset=+1]

examples/gherkin-to-asciidoc/snippet-templates/README.adoc

@@ -0,0 +1,132 @@
+= Gherkin to AsciiDoc — Snippets and Templates Example
+:toc: left
+
+== Description
+
+This example applies the Gherkin to AsciiDoc plugin against the same auth + billing feature/glue content used
+in the xref:../progress-tracking/README.adoc[progress-tracking example], but registers **four**
+`GenerateFeatureDocsTask` instances directly in `build.gradle` — one for every combination of `groupByFeature`
+(grouped vs flat) and `template` (with vs without) — so all four outputs can be compared side by side.
+
+A real project only needs *one* of these, normally configured through the `gherkinToAsciidoc { }` extension.
+This example bypasses the extension and registers the task type directly purely so it can demonstrate all
+four combinations from a single project.
+
+== Intent
+
+This example shows:
+
+* That `snippetDir` and the `listed.adoc`/`defined.adoc`/`implemented.adoc` snippet files are always written
+  once `trackProgress` is enabled, regardless of whether a `template` is configured.
+* How `groupByFeature` changes where those snippets are written: flat at `<snippetDir>/<status>.adoc`, or
+  split per feature at `<snippetDir>/<camelCaseFeatureTitle>/<status>.adoc`.
+* How setting `template` switches the generated document from embedding scenario titles verbatim to
+  referencing the snippets via `include::` directives.
+* That the two reference templates documented in the
+  link:../../../gherkin-to-asciidoc/README.adoc[plugin README]'s "Report Snippets and Custom Templates" section
+  (`templates/grouped.mustache` and `templates/flat.mustache`, copied verbatim into this example) reproduce
+  - once their `include::` directives are resolved - exactly the same document as not using a template at all.
+
+== Configuration
+
+[source,groovy]
+----
+def commonConfig = { GenerateFeatureDocsTask task ->
+    task.sourceDirs.from(
+            'src/test/resources/features-auth',
+            'src/test/resources/features-billing')
+    task.glueCodeDirs.from(
+            'src/test/java/com/arc_e_tect/example/auth/steps',
+            'src/test/java/com/arc_e_tect/example/billing/steps')
+    task.trackProgress.set(true)
+    task.includeSubDirs.set(true)
+    task.outputFileName.set('features.adoc')
+    task.projectDirectory.set(layout.projectDirectory)
+}
+
+tasks.register('generateGroupedNoTemplate', GenerateFeatureDocsTask) {
+    commonConfig(it)
+    groupByFeature.set(true)
+    outputDir.set(layout.buildDirectory.dir('generated-docs/grouped-no-template'))
+    snippetDir.set(layout.buildDirectory.dir('generated-docs/grouped-no-template/features/snippets'))
+}
+
+tasks.register('generateGroupedWithTemplate', GenerateFeatureDocsTask) {
+    commonConfig(it)
+    groupByFeature.set(true)
+    outputDir.set(layout.buildDirectory.dir('generated-docs/grouped-with-template'))
+    snippetDir.set(layout.buildDirectory.dir('generated-docs/grouped-with-template/features/snippets'))
+    template.set(file('templates/grouped.mustache'))
+}
+
+// generateFlatNoTemplate / generateFlatWithTemplate mirror the above with groupByFeature = false
+// and templates/flat.mustache. See build.gradle for the full listing.
+----
+
+== Build And Run
+
+[source,bash]
+----
+cd examples/gherkin-to-asciidoc/snippet-templates
+./gradlew generateAllReports
+----
+
+Or run any one combination individually, e.g. `./gradlew generateGroupedWithTemplate`.
+
+== What To Expect
+
+The build is expected to pass, writing four independent reports under `build/generated-docs/`.
+
+=== Grouped, no template — `grouped-no-template/features.adoc`
+
+Identical to the xref:../progress-tracking/README.adoc[progress-tracking example]'s output: scenario titles
+are embedded verbatim, grouped by feature within each status. The snippet files are still written to
+`grouped-no-template/features/snippets/`, split per feature (e.g. `userAuthentication/implemented.adoc`), even
+though nothing in this report references them.
+
+=== Grouped, with template — `grouped-with-template/features.adoc`
+
+[source,asciidoc]
+----
+== Implemented
+
+Scenarios whose every step has matching glue code.
+
+=== User authentication
+
+include::features/snippets/userAuthentication/implemented.adoc[]
+
+=== Invoice payment
+
+include::features/snippets/invoicePayment/implemented.adoc[]
+----
+
+Everything above `== Listed` (the intro, status legend, and progress summary table) is byte-for-byte identical
+to the no-template report. Only the per-status content changes: each `=== <Feature>` heading is now followed
+by an `include::` directive instead of the bullet list, pointing at exactly the snippet file
+`groupByFeature` would have written for that feature and status.
+
+=== Flat, no template — `flat-no-template/features.adoc`
+
+Same as above, but every status is one flat bullet list with no `=== <Feature>` headings — the `auth` and
+`billing` scenarios in `== Implemented` are listed together with no distinction between them.
+
+=== Flat, with template — `flat-with-template/features.adoc`
+
+[source,asciidoc]
+----
+== Implemented
+
+Scenarios whose every step has matching glue code.
+
+include::features/snippets/implemented.adoc[]
+----
+
+One flat `include::` per status, referencing `flat-with-template/features/snippets/implemented.adoc`, which
+itself contains:
+
+[source,asciidoc]
+----
+* Scenario: User logs in successfully
+* Scenario: User pays an invoice
+----

examples/gherkin-to-asciidoc/snippet-templates/build.gradle

@@ -0,0 +1,84 @@
+import com.arc_e_tect.gradle.gherkin.GenerateFeatureDocsTask
+
+plugins {
+    id 'java'
+    alias(libs.plugins.gherkin.to.asciidoc)
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(21)
+    }
+}
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation libs.cucumber.java
+}
+
+test {
+    failOnNoDiscoveredTests = false
+}
+
+// This example bypasses the gherkinToAsciidoc { } extension entirely and instead registers four
+// GenerateFeatureDocsTask instances directly, one per combination of groupByFeature and template,
+// all against the same auth + billing feature/glue content, so the four reports are easy to compare.
+//
+// A real project only needs ONE of these - typically configured via the extension, not like this.
+
+def commonConfig = { GenerateFeatureDocsTask task ->
+    task.sourceDirs.from(
+            'src/test/resources/features-auth',
+            'src/test/resources/features-billing')
+    task.glueCodeDirs.from(
+            'src/test/java/com/arc_e_tect/example/auth/steps',
+            'src/test/java/com/arc_e_tect/example/billing/steps')
+    task.trackProgress.set(true)
+    // trackProgress implies recursive scanning regardless of this value, but the property still
+    // needs a value assigned since this example bypasses the extension's conventions.
+    task.includeSubDirs.set(true)
+    task.outputFileName.set('features.adoc')
+    task.projectDirectory.set(layout.projectDirectory)
+}
+
+tasks.register('generateGroupedNoTemplate', GenerateFeatureDocsTask) {
+    commonConfig(it)
+    groupByFeature.set(true)
+    outputDir.set(layout.buildDirectory.dir('generated-docs/grouped-no-template'))
+    snippetDir.set(layout.buildDirectory.dir('generated-docs/grouped-no-template/features/snippets'))
+}
+
+tasks.register('generateGroupedWithTemplate', GenerateFeatureDocsTask) {
+    commonConfig(it)
+    groupByFeature.set(true)
+    outputDir.set(layout.buildDirectory.dir('generated-docs/grouped-with-template'))
+    snippetDir.set(layout.buildDirectory.dir('generated-docs/grouped-with-template/features/snippets'))
+    template.set(file('templates/grouped.mustache'))
+}
+
+tasks.register('generateFlatNoTemplate', GenerateFeatureDocsTask) {
+    commonConfig(it)
+    groupByFeature.set(false)
+    outputDir.set(layout.buildDirectory.dir('generated-docs/flat-no-template'))
+    snippetDir.set(layout.buildDirectory.dir('generated-docs/flat-no-template/features/snippets'))
+}
+
+tasks.register('generateFlatWithTemplate', GenerateFeatureDocsTask) {
+    commonConfig(it)
+    groupByFeature.set(false)
+    outputDir.set(layout.buildDirectory.dir('generated-docs/flat-with-template'))
+    snippetDir.set(layout.buildDirectory.dir('generated-docs/flat-with-template/features/snippets'))
+    template.set(file('templates/flat.mustache'))
+}
+
+tasks.register('generateAllReports') {
+    group = 'documentation'
+    description = 'Generates all four grouped/flat x template/no-template example reports.'
+    dependsOn tasks.named('generateGroupedNoTemplate'),
+            tasks.named('generateGroupedWithTemplate'),
+            tasks.named('generateFlatNoTemplate'),
+            tasks.named('generateFlatWithTemplate')
+}

examples/gherkin-to-asciidoc/snippet-templates/gradle.properties

@@ -0,0 +1,8 @@
+org.gradle.daemon=true
+org.gradle.parallel=true
+org.gradle.caching=true
+org.gradle.configuration-cache=true
+org.gradle.jvmargs=-Xmx8192m -Dfile.encoding=UTF-8
+
+group=com.arc-e-tect
+version = 0.0.1

examples/gherkin-to-asciidoc/snippet-templates/gradle/libs.versions.toml

@@ -0,0 +1,14 @@
+## Generated by $ ./gradlew refreshVersionsCatalog
+
+[plugins]
+
+gherkin-to-asciidoc = { id = "com.arc-e-tect.gherkin-to-asciidoc", version.ref = "gherkin-to-asciidoc" }
+
+[versions]
+
+gherkin-to-asciidoc = "1.2.0"
+cucumber-java        = "7.22.1"
+
+[libraries]
+
+cucumber-java = { module = "io.cucumber:cucumber-java", version.ref = "cucumber-java" }

examples/gherkin-to-asciidoc/snippet-templates/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,9 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip
+networkTimeout=10000
+retries=0
+retryBackOffMs=500
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists