feat(docs): add comprehensive Antora documentation structure

docs/antora-playbook.yml

@@ -0,0 +1,28 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json
+
+site:
+  title: Reqstool Gradle Plugin
+  url: https://github.com/reqstool/reqstool-java-gradle-plugin
+  start_page: reqstool-java-gradle-plugin::index.adoc
+
+content:
+  sources:
+    - url: ~+
+      branches: HEAD
+      start_path: docs
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+  supplemental_files:
+  - path: ui.yml
+    contents: |
+      static_files:
+      - .nojekyll
+  - path: .nojekyll
+asciidoc:
+  attributes:
+    kroki-server-url: https://kroki.io
+    kroki-fetch-diagram: true
+  extensions:
+    - asciidoctor-kroki

docs/antora.yml

@@ -0,0 +1,7 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraComponentSchema.json
+
+name: reqstool-java-gradle-plugin
+title: Reqstool Gradle Plugin
+version: 0.1.0
+nav:
+  - modules/ROOT/nav.adoc

docs/modules/ROOT/nav.adoc

@@ -0,0 +1 @@
+* xref:index.adoc[Start]

docs/modules/ROOT/pages/configuration.adoc

@@ -0,0 +1,146 @@
+== Configuration
+
+The plugin provides zero-configuration defaults, but you can customize if needed:
+
+=== Complete Configuration Example
+
+[source,gradle]
+----
+requirementsTool {
+    // Path to requirements annotations YAML
+    // Default: build/generated-sources/annotations/resources/annotations.yml
+    requirementsAnnotationsFile = file('build/custom-path/annotations.yml')
+
+    // Path to SVCS annotations YAML
+    // Default: build/generated-test-sources/test-annotations/resources/annotations.yml
+    svcsAnnotationsFile = file('build/custom-path/test-annotations.yml')
+
+    // Output directory for ZIP and combined annotations
+    // Default: build/reqstool
+    outputDirectory = file('build/custom-output')
+
+    // Dataset directory containing requirements.yml and optional files
+    // Default: ./reqstool
+    datasetPath = file('custom-reqstool-data')
+
+    // Test result file patterns
+    // Default: ['build/test-results/**/*.xml']
+    testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
+
+    // Skip entire plugin execution
+    // Default: false
+    skip = false
+
+    // Skip ZIP assembly but keep annotation combining
+    // Default: false
+    skipAssembleZipArtifact = false
+
+    // Skip artifact attachment for publishing
+    // Default: false
+    skipAttachZipArtifact = false
+}
+----
+
+=== Configuration Parameters
+
+==== requirementsAnnotationsFile
+
+The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    requirementsAnnotationsFile = file('build/generated-sources/annotations/resources/annotations.yml')
+}
+----
+
+==== svcsAnnotationsFile
+
+The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    svcsAnnotationsFile = file('build/generated-test-sources/test-annotations/resources/annotations.yml')
+}
+----
+
+==== outputDirectory
+
+The `outputDirectory` parameter specifies the path to where to put the generated output.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    outputDirectory = file('build/reqstool')
+}
+----
+
+==== datasetPath
+
+The `datasetPath` parameter specifies the path to the dataset directory containing requirements.yml and optional files.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    datasetPath = file('./reqstool')
+}
+----
+
+==== testResults
+
+The `testResults` parameter specifies one or more test result file patterns.
+Supports Ant-style pattern matching.
+
+[source,gradle]
+----
+requirementsTool {
+    testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
+}
+----
+
+==== skip
+
+Skip the execution of the entire plugin.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    skip = false
+}
+----
+
+==== skipAssembleZipArtifact
+
+Skip ZIP artifact assembly but continue with annotation combining.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    skipAssembleZipArtifact = false
+}
+----
+
+==== skipAttachZipArtifact
+
+Skip artifact attachment for publishing.
+Defaults to the value set below.
+
+[source,gradle]
+----
+requirementsTool {
+    skipAttachZipArtifact = false
+}
+----
+
+=== Notes
+
+* All path parameters support both absolute and relative paths
+* The plugin executes after the `check` task by default
+* Test result paths support Ant-style pattern matching

docs/modules/ROOT/pages/description.adoc

@@ -0,0 +1,58 @@
+== Description
+
+This Gradle plugin generates a ZIP artifact containing combined annotations and various reports for Reqstool. It provides zero-configuration defaults while allowing customization when needed.
+
+=== Features
+
+* *Zero-configuration*: Works out of the box with sensible defaults
+* *Automatic lifecycle integration*: Runs as part of the standard `build` task
+* *Maven publishing support*: Automatically registers ZIP artifact for publication
+* *Combines annotations*: Merges requirements annotations from implementation and test code
+* *Assembles ZIP artifact*: Creates structured ZIP containing requirements, test results, and configuration
+
+=== Quick Start
+
+==== Apply the Plugin
+
+[source,gradle]
+----
+plugins {
+    id 'io.github.reqstool.gradle-plugin' version '0.1.0'
+}
+----
+
+==== Default Behavior
+
+The plugin automatically:
+
+1. Runs after the `check` task (when tests complete)
+2. Combines annotation files from `build/generated-sources/` and `build/generated-test-sources/`
+3. Creates a ZIP artifact in `build/reqstool/` containing:
+   * `requirements.yml` (from `./reqstool/` directory)
+   * `software_verification_cases.yml` (optional)
+   * `manual_verification_results.yml` (optional)
+   * `annotations.yml` (combined/merged annotations)
+   * `test_results/` (XML test results from `build/test-results/`)
+   * `reqstool_config.yml` (configuration manifest)
+4. Registers the ZIP for Maven publication (if `maven-publish` plugin is applied)
+
+==== Minimal Setup
+
+Create a `reqstool/` directory in your project root with a `requirements.yml` file:
+
+[source]
+----
+my-project/
+├── build.gradle
+├── reqstool/
+│   └── requirements.yml  (mandatory)
+└── src/
+----
+
+Run `gradle build` and the ZIP artifact will be created automatically.
+
+=== Requirements
+
+* Gradle 9.0+
+* Java 17+
+* A `requirements.yml` file in the dataset directory (default: `./reqstool/`)

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,9 @@
+= Reqstool Gradle Plugin
+
+include::description.adoc[]
+
+include::configuration.adoc[]
+
+include::usage.adoc[]
+
+include::license.adoc[]

docs/modules/ROOT/pages/license.adoc

@@ -0,0 +1,3 @@
+== License
+
+This project is licensed under the MIT License.

docs/modules/ROOT/pages/usage.adoc

@@ -0,0 +1,66 @@
+== Usage
+
+To use the Reqstool Gradle Plugin, add the following configuration to your Gradle project's `build.gradle`:
+
+=== Basic Usage
+
+[source,gradle]
+----
+plugins {
+    id 'io.github.reqstool.gradle-plugin' version '0.1.0'
+}
+----
+
+The plugin will automatically integrate with the standard Gradle build lifecycle.
+
+=== Using Tasks Manually
+
+The main task can be invoked manually:
+
+[source,bash]
+----
+gradle assembleRequirements
+----
+
+=== With Maven Publishing
+
+When the `maven-publish` plugin is applied, the reqstool ZIP is automatically registered for publication:
+
+[source,gradle]
+----
+plugins {
+    id 'io.github.reqstool.gradle-plugin' version '0.1.0'
+    id 'maven-publish'
+}
+
+publishing {
+    repositories {
+        maven {
+            url = "https://your-repo.example.com/maven"
+        }
+    }
+}
+----
+
+The ZIP artifact will be published with classifier `reqstool` (e.g., `my-app-1.0.0-reqstool.zip`).
+
+=== Available Tasks
+
+==== assembleRequirements
+
+Main task that:
+
+* Depends on `check` task (ensures tests have run)
+* Combines annotation files
+* Assembles ZIP artifact
+* Runs automatically as part of `build` task
+
+=== Default Lifecycle
+
+The plugin automatically integrates into the standard Gradle build:
+
+1. Plugin is applied
+2. `assembleRequirements` task is created and configured
+3. Task runs after `check` (when all tests complete)
+4. ZIP artifact is created in `build/reqstool/`
+5. If `maven-publish` plugin is applied, artifact is registered for publication