Skip to content

Commit 2b1b29c

Browse files
authored
docs: add complete configuration reference table to README (#160)
* docs: add complete configuration reference table to README Adds a full configuration table documenting all plugin parameters with types, defaults, and descriptions. Adds dataset directory reference, full configuration example, command-line override syntax, and a goal reference section. Aligns README structure with reqstool-java-gradle-plugin. Signed-off-by: Jimisola Laursen <jimisola@jimisola.com> * docs: update Antora docs with configuration reference table and usage improvements - Rewrite configuration.adoc with a reference table, dataset directory table, minimal/complete configuration examples, and command-line override syntax - Update usage.adoc with goal reference, lifecycle diagram, and cleaner section structure - Update index.adoc for consistent structure with Gradle plugin docs Signed-off-by: Jimisola Laursen <jimisola@jimisola.com> --------- Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>
1 parent f6034dd commit 2b1b29c

4 files changed

Lines changed: 202 additions & 141 deletions

File tree

‎README.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Maven build plugin for [reqstool](https://github.com/reqstool/reqstool-client) t
1212

1313
Collects `@Requirements` and `@SVCs` annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI.
1414

15+
The plugin binds to the `verify` lifecycle phase and runs automatically after tests complete. No additional lifecycle configuration is needed in most projects.
16+
1517
## Installation
1618

1719
Add the plugin to your `pom.xml`:
@@ -34,6 +36,83 @@ Add the plugin to your `pom.xml`:
3436
</plugin>
3537
```
3638

39+
## Configuration
40+
41+
All parameters are optional. Defaults match the standard Maven project layout.
42+
43+
| Parameter | Type | Default | Description |
44+
|---|---|---|---|
45+
| `requirementsAnnotationsFile` | `File` | `${project.build.directory}/generated-sources/annotations/resources/annotations.yml` | Requirements annotations YAML file generated by the annotation processor for the main source set |
46+
| `svcsAnnotationsFile` | `File` | `${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml` | SVCs annotations YAML file generated by the annotation processor for the test source set |
47+
| `outputDirectory` | `File` | `${project.build.directory}/reqstool` | Output directory for the ZIP artifact and combined annotations file |
48+
| `datasetPath` | `File` | `${project.basedir}/reqstool` | Directory containing `requirements.yml` and optional supporting files |
49+
| `testResults` | `String[]` | _(none)_ | Ant-style glob patterns for test result XML files to include in the ZIP |
50+
| `skip` | `boolean` | `false` | Skip all plugin execution |
51+
| `skipAssembleZipArtifact` | `boolean` | `false` | Skip ZIP assembly; annotations are still combined into `annotations.yml` |
52+
| `skipAttachZipArtifact` | `boolean` | `false` | Skip attaching the ZIP artifact to the Maven project |
53+
54+
### Dataset directory
55+
56+
The `datasetPath` directory must contain at minimum a `requirements.yml` file. Optional files in the same directory are included if present:
57+
58+
| File | Required |
59+
|---|---|
60+
| `requirements.yml` | Yes |
61+
| `software_verification_cases.yml` | No |
62+
| `manual_verification_results.yml` | No |
63+
64+
### Full configuration example
65+
66+
```xml
67+
<plugin>
68+
<groupId>io.github.reqstool</groupId>
69+
<artifactId>reqstool-maven-plugin</artifactId>
70+
<version>1.0.4</version>
71+
<executions>
72+
<execution>
73+
<goals>
74+
<goal>assemble-and-attach-zip-artifact</goal>
75+
</goals>
76+
</execution>
77+
</executions>
78+
<configuration>
79+
<requirementsAnnotationsFile>
80+
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
81+
</requirementsAnnotationsFile>
82+
<svcsAnnotationsFile>
83+
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
84+
</svcsAnnotationsFile>
85+
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
86+
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
87+
<testResults>
88+
<testResult>target/surefire-reports/**/*.xml</testResult>
89+
<testResult>target/failsafe-reports/**/*.xml</testResult>
90+
</testResults>
91+
<skip>false</skip>
92+
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
93+
<skipAttachZipArtifact>false</skipAttachZipArtifact>
94+
</configuration>
95+
</plugin>
96+
```
97+
98+
### Command-line overrides
99+
100+
All parameters can be overridden on the command line using the `reqstool.` prefix:
101+
102+
```bash
103+
mvn verify -Dreqstool.skip=true
104+
mvn verify -Dreqstool.datasetPath=/custom/path
105+
mvn verify -Dreqstool.skipAssembleZipArtifact=true
106+
```
107+
108+
## Goal reference
109+
110+
### `assemble-and-attach-zip-artifact`
111+
112+
Default phase: `verify`
113+
114+
Combines requirements and SVCs annotations, writes a merged `annotations.yml` to `outputDirectory`, and (unless `skipAssembleZipArtifact` is set) assembles a ZIP artifact at `<outputDirectory>/<finalName>-reqstool.zip`. The ZIP is attached to the Maven project with classifier `reqstool` and extension `zip`.
115+
37116
## Usage
38117

39118
```bash
Lines changed: 82 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,141 +1,115 @@
1-
== Configuration
1+
= Configuration
22

3-
The plugin provides sensible defaults, but you can customize if needed by adding a `<configuration>` block in your `pom.xml`:
3+
The plugin provides sensible defaults that match the standard Maven project layout.
4+
Override only what you need by adding a `<configuration>` block in your `pom.xml`.
45

5-
=== Complete Configuration Example
6+
== Configuration reference
67

7-
[source,xml]
8-
----
9-
<configuration>
10-
<!-- Path to requirements annotations YAML -->
11-
<!-- Default: ${project.build.directory}/generated-sources/annotations/resources/annotations.yml -->
12-
<requirementsAnnotationsFile>
13-
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
14-
</requirementsAnnotationsFile>
8+
[cols="1,1,2,2",options="header"]
9+
|===
10+
|Parameter |Type |Default |Description
1511

16-
<!-- Path to SVCS (Software Verification Cases) annotations YAML -->
17-
<!-- Default: ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml -->
18-
<svcsAnnotationsFile>
19-
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
20-
</svcsAnnotationsFile>
12+
|`requirementsAnnotationsFile`
13+
|`File`
14+
|`${project.build.directory}/generated-sources/annotations/resources/annotations.yml`
15+
|Requirements annotations YAML file generated by the annotation processor for the main source set
2116

22-
<!-- Output directory for ZIP and combined annotations -->
23-
<!-- Default: ${project.build.directory}/reqstool -->
24-
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
17+
|`svcsAnnotationsFile`
18+
|`File`
19+
|`${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml`
20+
|SVCs annotations YAML file generated by the annotation processor for the test source set
2521

26-
<!-- Dataset directory containing requirements.yml and optional files -->
27-
<!-- Default: ${project.basedir}/reqstool -->
28-
<datasetPath>${project.basedir}/reqstool</datasetPath>
22+
|`outputDirectory`
23+
|`File`
24+
|`${project.build.directory}/reqstool`
25+
|Output directory for the ZIP artifact and combined `annotations.yml`
2926

30-
<!-- Test result file patterns (Ant-style) -->
31-
<testResults>
32-
<testResult>target/surefire-reports/**/*.xml</testResult>
33-
<testResult>target/failsafe-reports/**/*.xml</testResult>
34-
</testResults>
27+
|`datasetPath`
28+
|`File`
29+
|`${project.basedir}/reqstool`
30+
|Directory containing `requirements.yml` and optional supporting files
3531

36-
<!-- Skip entire plugin execution (default: false) -->
37-
<skip>false</skip>
32+
|`testResults`
33+
|`String[]`
34+
|_(none)_
35+
|Ant-style glob patterns for test result XML files to include in the ZIP
3836

39-
<!-- Skip ZIP assembly but keep annotation combining (default: false) -->
40-
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
37+
|`skip`
38+
|`boolean`
39+
|`false`
40+
|Skip all plugin execution
4141

42-
<!-- Skip artifact attachment for deployment (default: false) -->
43-
<skipAttachZipArtifact>false</skipAttachZipArtifact>
44-
</configuration>
45-
----
46-
47-
=== Configuration Parameters
48-
49-
==== requirementsAnnotationsFile
42+
|`skipAssembleZipArtifact`
43+
|`boolean`
44+
|`false`
45+
|Skip ZIP assembly; annotations are still combined into `annotations.yml`
5046

51-
The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file.
52-
Defaults to the value set below.
53-
54-
[source,xml]
55-
----
56-
<requirementsAnnotationsFile>
57-
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
58-
</requirementsAnnotationsFile>
59-
----
47+
|`skipAttachZipArtifact`
48+
|`boolean`
49+
|`false`
50+
|Skip attaching the ZIP artifact to the Maven project
51+
|===
6052

61-
==== svcsAnnotationsFile
53+
== Dataset directory
6254

63-
The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file.
64-
Defaults to the value set below.
55+
The `datasetPath` directory must contain at minimum a `requirements.yml` file.
56+
Optional files in the same directory are included if present.
6557

66-
[source,xml]
67-
----
68-
<svcsAnnotationsFile>
69-
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
70-
</svcsAnnotationsFile>
71-
----
58+
[cols="1,1",options="header"]
59+
|===
60+
|File |Required
7261

73-
==== outputDirectory
62+
|`requirements.yml`
63+
|Yes
7464

75-
The `outputDirectory` parameter specifies the path to where to put the generated output.
76-
Defaults to the value set below.
65+
|`software_verification_cases.yml`
66+
|No
7767

78-
[source,xml]
79-
----
80-
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
81-
----
68+
|`manual_verification_results.yml`
69+
|No
70+
|===
8271

83-
==== datasetPath
72+
== Minimal configuration
8473

85-
The `datasetPath` parameter specifies the path to the dataset directory containing `requirements.yml` and optional files.
86-
Defaults to the value set below.
74+
Only `datasetPath` needs to be set when the dataset lives outside the default `reqstool/` directory:
8775

8876
[source,xml]
8977
----
90-
<datasetPath>${project.basedir}/reqstool</datasetPath>
91-
----
92-
93-
==== testResults
94-
95-
The `testResults` parameter specifies one or more test result file patterns.
96-
Supports Ant-style pattern matching.
97-
98-
[source,xml]
99-
----
100-
<testResults>
101-
<testResult>target/surefire-reports/**/*.xml</testResult>
102-
<testResult>target/failsafe-reports/**/*.xml</testResult>
103-
</testResults>
104-
----
105-
106-
==== skip
107-
108-
Skip the execution of the entire plugin.
109-
Defaults to `false`.
110-
111-
[source,xml]
112-
----
113-
<skip>false</skip>
78+
<configuration>
79+
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
80+
</configuration>
11481
----
11582

116-
==== skipAssembleZipArtifact
117-
118-
Skip ZIP artifact assembly but continue with annotation combining.
119-
Defaults to `false`.
83+
== Complete configuration example
12084

12185
[source,xml]
12286
----
123-
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
87+
<configuration>
88+
<requirementsAnnotationsFile>
89+
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
90+
</requirementsAnnotationsFile>
91+
<svcsAnnotationsFile>
92+
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
93+
</svcsAnnotationsFile>
94+
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
95+
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
96+
<testResults>
97+
<testResult>target/surefire-reports/**/*.xml</testResult>
98+
<testResult>target/failsafe-reports/**/*.xml</testResult>
99+
</testResults>
100+
<skip>false</skip>
101+
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
102+
<skipAttachZipArtifact>false</skipAttachZipArtifact>
103+
</configuration>
124104
----
125105

126-
==== skipAttachZipArtifact
106+
== Command-line overrides
127107

128-
Skip artifact attachment for deployment.
129-
Defaults to `false`.
108+
All parameters can be overridden on the command line using the `reqstool.` prefix:
130109

131-
[source,xml]
110+
[source,bash]
132111
----
133-
<skipAttachZipArtifact>false</skipAttachZipArtifact>
112+
mvn verify -Dreqstool.skip=true
113+
mvn verify -Dreqstool.datasetPath=/custom/path
114+
mvn verify -Dreqstool.skipAssembleZipArtifact=true
134115
----
135-
136-
=== Notes
137-
138-
* All path parameters support both absolute and relative paths
139-
* Maven property placeholders (`${...}`) can be used in all configuration values
140-
* The plugin executes in the `verify` phase by default
141-
* Test result paths support Ant-style pattern matching

‎docs/modules/ROOT/pages/index.adoc‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This Maven plugin generates a ZIP artifact containing combined annotations and v
1212

1313
== Quick Start
1414

15-
== Add the Plugin
15+
=== Add the plugin
1616

1717
[source,xml]
1818
----
@@ -29,35 +29,38 @@ This Maven plugin generates a ZIP artifact containing combined annotations and v
2929
</goals>
3030
</execution>
3131
</executions>
32+
<configuration>
33+
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
34+
</configuration>
3235
</plugin>
3336
</plugins>
3437
</build>
3538
----
3639

37-
== Default Behavior
40+
=== Default behavior
3841

3942
The plugin automatically:
4043

4144
1. Runs during the `verify` phase (after all tests complete)
4245
2. Combines annotation files from `target/generated-sources/` and `target/generated-test-sources/`
4346
3. Creates a ZIP artifact in `target/reqstool/` containing:
44-
* `requirements.yml` (from `./reqstool/` directory)
47+
* `requirements.yml` (from `datasetPath` directory)
4548
* `software_verification_cases.yml` (optional)
4649
* `manual_verification_results.yml` (optional)
47-
* `annotations.yml` (combined/merged annotations)
48-
* `test_results/` (XML test results from Surefire and Failsafe)
50+
* `annotations.yml` (combined annotations)
51+
* `test_results/` (XML test results matching `testResults` patterns)
4952
* `reqstool_config.yml` (configuration manifest)
5053
4. Attaches the ZIP for deployment to Maven repositories
5154

52-
== Minimal Setup
55+
=== Minimal setup
5356

54-
Create a `reqstool/` directory in your project root with a `requirements.yml` file:
57+
Create a dataset directory with a `requirements.yml` file:
5558

5659
[source]
5760
----
5861
my-project/
5962
├── pom.xml
60-
├── reqstool/
63+
├── docs/reqstool/
6164
│ └── requirements.yml (mandatory)
6265
└── src/
6366
----
@@ -68,7 +71,7 @@ Run `mvn verify` and the ZIP artifact will be created automatically.
6871

6972
* Maven 3.9+
7073
* Java 21+
71-
* A `requirements.yml` file in the dataset directory (default: `./reqstool/`)
74+
* A `requirements.yml` file in the dataset directory (default: `reqstool/`)
7275

7376
== License
7477

0 commit comments

Comments
 (0)