From b473a489e6fed8e9aa73094ec6e5a6724f0a082c Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Wed, 25 Feb 2026 12:14:06 +0100 Subject: [PATCH] chore(docs): add comprehensive Antora documentation structure Create Antora-based documentation structure matching the Maven plugin pattern: - antora.yml: Component descriptor with plugin metadata - antora-playbook.yml: Playbook configuration for building the documentation site - modules/ROOT/nav.adoc: Navigation structure - modules/ROOT/pages/: - index.adoc: Main documentation page - description.adoc: Features, quick start, and requirements - configuration.adoc: Configuration parameters with examples - usage.adoc: Usage examples and task information - license.adoc: License information Content adapted from README.adoc with Gradle-specific details and examples. Resolves #21 Signed-off-by: Jimisola Laursen --- docs/antora-playbook.yml | 28 ++++ docs/antora.yml | 7 + docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/configuration.adoc | 146 +++++++++++++++++++++ docs/modules/ROOT/pages/description.adoc | 58 ++++++++ docs/modules/ROOT/pages/index.adoc | 9 ++ docs/modules/ROOT/pages/license.adoc | 3 + docs/modules/ROOT/pages/usage.adoc | 66 ++++++++++ 8 files changed, 318 insertions(+) create mode 100644 docs/antora-playbook.yml create mode 100644 docs/antora.yml create mode 100644 docs/modules/ROOT/nav.adoc create mode 100644 docs/modules/ROOT/pages/configuration.adoc create mode 100644 docs/modules/ROOT/pages/description.adoc create mode 100644 docs/modules/ROOT/pages/index.adoc create mode 100644 docs/modules/ROOT/pages/license.adoc create mode 100644 docs/modules/ROOT/pages/usage.adoc diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml new file mode 100644 index 0000000..1ace234 --- /dev/null +++ b/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 diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..f29b6d9 --- /dev/null +++ b/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 diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..7917907 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1 @@ +* xref:index.adoc[Start] diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc new file mode 100644 index 0000000..afbe107 --- /dev/null +++ b/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 diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc new file mode 100644 index 0000000..03442f5 --- /dev/null +++ b/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/`) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..b96830b --- /dev/null +++ b/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[] diff --git a/docs/modules/ROOT/pages/license.adoc b/docs/modules/ROOT/pages/license.adoc new file mode 100644 index 0000000..f673488 --- /dev/null +++ b/docs/modules/ROOT/pages/license.adoc @@ -0,0 +1,3 @@ +== License + +This project is licensed under the MIT License. diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc new file mode 100644 index 0000000..da6dbb6 --- /dev/null +++ b/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