Skip to content

Commit b473a48

Browse files
jimisolajimisola
committed
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 <jimisola@jimisola.com>
1 parent 55bf4a9 commit b473a48

8 files changed

Lines changed: 318 additions & 0 deletions

File tree

‎docs/antora-playbook.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json
2+
3+
site:
4+
title: Reqstool Gradle Plugin
5+
url: https://github.com/reqstool/reqstool-java-gradle-plugin
6+
start_page: reqstool-java-gradle-plugin::index.adoc
7+
8+
content:
9+
sources:
10+
- url: ~+
11+
branches: HEAD
12+
start_path: docs
13+
ui:
14+
bundle:
15+
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
16+
snapshot: true
17+
supplemental_files:
18+
- path: ui.yml
19+
contents: |
20+
static_files:
21+
- .nojekyll
22+
- path: .nojekyll
23+
asciidoc:
24+
attributes:
25+
kroki-server-url: https://kroki.io
26+
kroki-fetch-diagram: true
27+
extensions:
28+
- asciidoctor-kroki

‎docs/antora.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraComponentSchema.json
2+
3+
name: reqstool-java-gradle-plugin
4+
title: Reqstool Gradle Plugin
5+
version: 0.1.0
6+
nav:
7+
- modules/ROOT/nav.adoc

‎docs/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* xref:index.adoc[Start]

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

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
== Configuration
2+
3+
The plugin provides zero-configuration defaults, but you can customize if needed:
4+
5+
=== Complete Configuration Example
6+
7+
[source,gradle]
8+
----
9+
requirementsTool {
10+
// Path to requirements annotations YAML
11+
// Default: build/generated-sources/annotations/resources/annotations.yml
12+
requirementsAnnotationsFile = file('build/custom-path/annotations.yml')
13+
14+
// Path to SVCS annotations YAML
15+
// Default: build/generated-test-sources/test-annotations/resources/annotations.yml
16+
svcsAnnotationsFile = file('build/custom-path/test-annotations.yml')
17+
18+
// Output directory for ZIP and combined annotations
19+
// Default: build/reqstool
20+
outputDirectory = file('build/custom-output')
21+
22+
// Dataset directory containing requirements.yml and optional files
23+
// Default: ./reqstool
24+
datasetPath = file('custom-reqstool-data')
25+
26+
// Test result file patterns
27+
// Default: ['build/test-results/**/*.xml']
28+
testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
29+
30+
// Skip entire plugin execution
31+
// Default: false
32+
skip = false
33+
34+
// Skip ZIP assembly but keep annotation combining
35+
// Default: false
36+
skipAssembleZipArtifact = false
37+
38+
// Skip artifact attachment for publishing
39+
// Default: false
40+
skipAttachZipArtifact = false
41+
}
42+
----
43+
44+
=== Configuration Parameters
45+
46+
==== requirementsAnnotationsFile
47+
48+
The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file.
49+
Defaults to the value set below.
50+
51+
[source,gradle]
52+
----
53+
requirementsTool {
54+
requirementsAnnotationsFile = file('build/generated-sources/annotations/resources/annotations.yml')
55+
}
56+
----
57+
58+
==== svcsAnnotationsFile
59+
60+
The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file.
61+
Defaults to the value set below.
62+
63+
[source,gradle]
64+
----
65+
requirementsTool {
66+
svcsAnnotationsFile = file('build/generated-test-sources/test-annotations/resources/annotations.yml')
67+
}
68+
----
69+
70+
==== outputDirectory
71+
72+
The `outputDirectory` parameter specifies the path to where to put the generated output.
73+
Defaults to the value set below.
74+
75+
[source,gradle]
76+
----
77+
requirementsTool {
78+
outputDirectory = file('build/reqstool')
79+
}
80+
----
81+
82+
==== datasetPath
83+
84+
The `datasetPath` parameter specifies the path to the dataset directory containing requirements.yml and optional files.
85+
Defaults to the value set below.
86+
87+
[source,gradle]
88+
----
89+
requirementsTool {
90+
datasetPath = file('./reqstool')
91+
}
92+
----
93+
94+
==== testResults
95+
96+
The `testResults` parameter specifies one or more test result file patterns.
97+
Supports Ant-style pattern matching.
98+
99+
[source,gradle]
100+
----
101+
requirementsTool {
102+
testResults = ['build/test-results/**/*.xml', 'build/custom-tests/**/*.xml']
103+
}
104+
----
105+
106+
==== skip
107+
108+
Skip the execution of the entire plugin.
109+
Defaults to the value set below.
110+
111+
[source,gradle]
112+
----
113+
requirementsTool {
114+
skip = false
115+
}
116+
----
117+
118+
==== skipAssembleZipArtifact
119+
120+
Skip ZIP artifact assembly but continue with annotation combining.
121+
Defaults to the value set below.
122+
123+
[source,gradle]
124+
----
125+
requirementsTool {
126+
skipAssembleZipArtifact = false
127+
}
128+
----
129+
130+
==== skipAttachZipArtifact
131+
132+
Skip artifact attachment for publishing.
133+
Defaults to the value set below.
134+
135+
[source,gradle]
136+
----
137+
requirementsTool {
138+
skipAttachZipArtifact = false
139+
}
140+
----
141+
142+
=== Notes
143+
144+
* All path parameters support both absolute and relative paths
145+
* The plugin executes after the `check` task by default
146+
* Test result paths support Ant-style pattern matching

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
== Description
2+
3+
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.
4+
5+
=== Features
6+
7+
* *Zero-configuration*: Works out of the box with sensible defaults
8+
* *Automatic lifecycle integration*: Runs as part of the standard `build` task
9+
* *Maven publishing support*: Automatically registers ZIP artifact for publication
10+
* *Combines annotations*: Merges requirements annotations from implementation and test code
11+
* *Assembles ZIP artifact*: Creates structured ZIP containing requirements, test results, and configuration
12+
13+
=== Quick Start
14+
15+
==== Apply the Plugin
16+
17+
[source,gradle]
18+
----
19+
plugins {
20+
id 'io.github.reqstool.gradle-plugin' version '0.1.0'
21+
}
22+
----
23+
24+
==== Default Behavior
25+
26+
The plugin automatically:
27+
28+
1. Runs after the `check` task (when tests complete)
29+
2. Combines annotation files from `build/generated-sources/` and `build/generated-test-sources/`
30+
3. Creates a ZIP artifact in `build/reqstool/` containing:
31+
* `requirements.yml` (from `./reqstool/` directory)
32+
* `software_verification_cases.yml` (optional)
33+
* `manual_verification_results.yml` (optional)
34+
* `annotations.yml` (combined/merged annotations)
35+
* `test_results/` (XML test results from `build/test-results/`)
36+
* `reqstool_config.yml` (configuration manifest)
37+
4. Registers the ZIP for Maven publication (if `maven-publish` plugin is applied)
38+
39+
==== Minimal Setup
40+
41+
Create a `reqstool/` directory in your project root with a `requirements.yml` file:
42+
43+
[source]
44+
----
45+
my-project/
46+
├── build.gradle
47+
├── reqstool/
48+
│ └── requirements.yml (mandatory)
49+
└── src/
50+
----
51+
52+
Run `gradle build` and the ZIP artifact will be created automatically.
53+
54+
=== Requirements
55+
56+
* Gradle 9.0+
57+
* Java 17+
58+
* A `requirements.yml` file in the dataset directory (default: `./reqstool/`)

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
= Reqstool Gradle Plugin
2+
3+
include::description.adoc[]
4+
5+
include::configuration.adoc[]
6+
7+
include::usage.adoc[]
8+
9+
include::license.adoc[]

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
== License
2+
3+
This project is licensed under the MIT License.

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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
== Usage
2+
3+
To use the Reqstool Gradle Plugin, add the following configuration to your Gradle project's `build.gradle`:
4+
5+
=== Basic Usage
6+
7+
[source,gradle]
8+
----
9+
plugins {
10+
id 'io.github.reqstool.gradle-plugin' version '0.1.0'
11+
}
12+
----
13+
14+
The plugin will automatically integrate with the standard Gradle build lifecycle.
15+
16+
=== Using Tasks Manually
17+
18+
The main task can be invoked manually:
19+
20+
[source,bash]
21+
----
22+
gradle assembleRequirements
23+
----
24+
25+
=== With Maven Publishing
26+
27+
When the `maven-publish` plugin is applied, the reqstool ZIP is automatically registered for publication:
28+
29+
[source,gradle]
30+
----
31+
plugins {
32+
id 'io.github.reqstool.gradle-plugin' version '0.1.0'
33+
id 'maven-publish'
34+
}
35+
36+
publishing {
37+
repositories {
38+
maven {
39+
url = "https://your-repo.example.com/maven"
40+
}
41+
}
42+
}
43+
----
44+
45+
The ZIP artifact will be published with classifier `reqstool` (e.g., `my-app-1.0.0-reqstool.zip`).
46+
47+
=== Available Tasks
48+
49+
==== assembleRequirements
50+
51+
Main task that:
52+
53+
* Depends on `check` task (ensures tests have run)
54+
* Combines annotation files
55+
* Assembles ZIP artifact
56+
* Runs automatically as part of `build` task
57+
58+
=== Default Lifecycle
59+
60+
The plugin automatically integrates into the standard Gradle build:
61+
62+
1. Plugin is applied
63+
2. `assembleRequirements` task is created and configured
64+
3. Task runs after `check` (when all tests complete)
65+
4. ZIP artifact is created in `build/reqstool/`
66+
5. If `maven-publish` plugin is applied, artifact is registered for publication

0 commit comments

Comments
 (0)