docs: documentation overhaul (#143)

* docs: documentation overhaul

- Standardize README.md with consistent badges and structure
- Add CONTRIBUTING.md with repo-specific dev setup
- Add/update Antora docs structure
- Remove per-repo GitHub Pages workflow
- Point documentation badge to central site

Signed-off-by: jimisola <jimisola@jimisola.com>

* docs: streamline nav and page structure

- Separate nav items instead of single monolithic page
- Merge description.adoc content into index.adoc
- Add license section to index.adoc
- Change nav label from All to Overview

Signed-off-by: jimisola <jimisola@jimisola.com>

* docs: use lowercase reqstool consistently

Signed-off-by: jimisola <jimisola@jimisola.com>

* docs: add cross-component xrefs to Maven and Gradle plugins

Signed-off-by: jimisola <jimisola@jimisola.com>

---------

Signed-off-by: jimisola <jimisola@jimisola.com>
Co-authored-by: Jimisola Laursen <jimisola.laursen@resurs.se>

Author: jimisola

.github/workflows/publish_pages.yml

@@ -0,0 +1,23 @@
+# Contributing to reqstool-java-annotations
+
+Thank you for your interest in contributing!
+
+For DCO sign-off, commit conventions, and code review process, see the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md).
+
+## Prerequisites
+
+- Java 21+
+- Maven 3.9+
+
+## Setup
+
+```bash
+git clone https://github.com/reqstool/reqstool-java-annotations.git
+cd reqstool-java-annotations
+```
+
+## Build & Test
+
+```bash
+mvn verify
+```

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+[![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-annotations?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-java-annotations/pulse)
+[![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-java-annotations?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-annotations/issues)
+[![License](https://img.shields.io/github/license/reqstool/reqstool-java-annotations?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/)
+[![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-annotations/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-annotations/actions/workflows/build.yml)
+[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io)
+
+# Reqstool Java Annotations
+
+Java annotations for [reqstool](https://github.com/reqstool/reqstool-client) requirements traceability.
+
+## Overview
+
+Provides `@Requirements` and `@SVCs` annotations for linking Java code to requirements and software verification cases. Used together with the [Maven Plugin](https://github.com/reqstool/reqstool-java-maven-plugin) or [Gradle Plugin](https://github.com/reqstool/reqstool-java-gradle-plugin).
+
+## Installation
+
+Add the dependency to your project:
+
+### Maven
+
+```xml
+<dependency>
+    <groupId>io.github.reqstool</groupId>
+    <artifactId>reqstool-java-annotations</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+### Gradle
+
+```groovy
+implementation 'io.github.reqstool:reqstool-java-annotations:1.0.0'
+```
+
+## Usage
+
+```java
+import io.github.reqstool.annotations.Requirements;
+import io.github.reqstool.annotations.SVCs;
+
+@Requirements({"REQ_001", "REQ_002"})
+public class MyService {
+    // Implementation
+}
+
+@Test
+@SVCs("SVC_001")
+public void testMyService() {
+    // Test
+}
+```
+
+## Documentation
+
+Full documentation can be found [here](https://reqstool.github.io).
+
+## Contributing
+
+See the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT License.

README.adoc

@@ -1,4 +1,5 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json
+# For local development only. Published site: https://reqstool.github.io
 
 site:
   title: Reqstool Java Annotations Documentation

README.md

@@ -1,5 +1,4 @@
-* xref:index.adoc[All]
-* xref:description.adoc[Description]
+* xref:index.adoc[Overview]
 * xref:installation.adoc[Installation]
 * xref:usage.adoc[Usage]
 * xref:debugging.adoc[Debugging]

docs/antora-playbook.yml

@@ -1,9 +1,14 @@
-= Reqstool Java Annotations
+= reqstool Java Annotations
 
-include::description.adoc[]
+This provides Java annotations and processing of annotated code.
 
-include::installation.adoc[]
+Enables the usage of `@Requirements` and `@SVCs` annotations and processors to collect, format and write annotations data to yaml files.
 
-include::usage.adoc[]
+== Related components
 
-include::debugging.adoc[]
+* xref:reqstool-java-maven-plugin::index.adoc[Maven Plugin] -- packages annotations into a reqstool artifact during Maven builds
+* xref:reqstool-java-gradle-plugin::index.adoc[Gradle Plugin] -- packages annotations into a reqstool artifact during Gradle builds
+
+== License
+
+MIT License.