reqstool · jimisola · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
diff --git a/.github/workflows/publish_gh_pages.yml b/.github/workflows/publish_gh_pages.yml
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,25 @@
+# Contributing to reqstool-python-poetry-plugin
+
+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
+
+- Python 3.13+
+- [Poetry](https://python-poetry.org/)
+
+## Setup
+
+```bash
+git clone https://github.com/reqstool/reqstool-python-poetry-plugin.git
+cd reqstool-python-poetry-plugin
+poetry install
+```
+
+## Build & Test
+
+```bash
+poetry build
+poetry run pytest
+```
diff --git a/README.md b/README.md
@@ -1,60 +1,25 @@
-
 [![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-python-poetry-plugin?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-python-poetry-plugin/pulse)
 [![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-python-poetry-plugin?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-python-poetry-plugin/issues)
 [![License](https://img.shields.io/github/license/reqstool/reqstool-python-poetry-plugin?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/)
 [![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-python-poetry-plugin/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-python-poetry-plugin/actions/workflows/build.yml)
-[![Static Badge](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io/reqstool-python-poetry-plugin/reqstool-python-poetry-plugin/0.0.2/index.html)
+[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io)
 
 # Reqstool Python Poetry Plugin
 
 > [!WARNING]
 > Poetry plugin support is currently untested. Functionality may be broken. Contributions welcome.
 
-## Description
-
-This provides an application plugin for Poetry that runs during `poetry build` and `poetry install`.
-
-The plugin collects decorated code, formatting it and writing it to a annotations.yml file saved to the `build/reqstool/` folder, utilizing the `reqstool-python-decorators` package for the processing.
-
+Poetry build plugin for [reqstool](https://github.com/reqstool/reqstool-client) that collects decorated code and generates `annotations.yml` during `poetry build`.
 
 ## Installation
 
-### Plugin
-
-The package name is `reqstool-python-poetry-plugin`.
-
-* Using poetry:
-
-```
-$poetry add reqstool-python-poetry-plugin
-```
-
-* pip install (unsure if working as intended):
-
-```
-$pip install reqstool-python-poetry-plugin
-```
-
-### Dependencies
-
-#### reqstool-decorators
-
-The plugin reads decorators available in the `reqstool-python-decorators` package.
-
-```
-$pip install reqstool-python-decorators
-```
-
-pyproject.toml
-
-```
-[tool.poetry.dependencies]
-reqstool-python-decorators = "<version>"
+```bash
+poetry add reqstool-python-poetry-plugin
 ```
 
-### Configuration
+## Usage
 
-The plugin is configured in the `pyproject.toml` file.
+Configure the plugin in `pyproject.toml`:
 
 ```toml
 [tool.reqstool]
@@ -64,41 +29,16 @@ dataset_directory = "docs/reqstool"
 output_directory = "build/reqstool"
 ```
 
-This specifies where the plugin should be applied: `sources`, where test reports are located: `test_results`, where reqstool files are located: `dataset_directory` and output directory: `output_directory`.
-
-
-## Usage
-
-### Decorators
-
-Used to decorate your code as seen in the examples below, the decorator processing that runs during the build process collects data from the decorated code.
-
-Import decorators:
-
-```
-from reqstool-python-decorators.decorators.decorators import Requirements, SVCs
-```
-
-Example usage of the decorators:
-
-```
-@Requirements("REQ_111", "REQ_222")
-def somefunction():
-```
-
-```
-@SVCs("SVC_111", "SVC_222")
-def test_somefunction():
-```
-
-### Poetry build
+The plugin uses [reqstool-python-decorators](https://github.com/reqstool/reqstool-python-decorators) for processing.
 
-When running `$poetry build` the plugin will generate an `annotations.yml` file in the `build/reqstool/` folder and a `reqstool_config.yml` in the project root (which is bundled into the sdist and then removed after the build completes).
+## Documentation
 
-When running `$poetry install` the plugin will update `pyproject.toml` with the necessary `include` entries for reqstool files.
+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
 
-This project is licensed under the MIT License - see the LICENSE.md file for details.
+MIT License.
diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml
@@ -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 Python Poetry Plugin Documentation

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -1,4 +1,3 @@
-* xref:index.adoc[All]
-* xref:description.adoc[Description]
-* xref:installation.adoc[Installation]
-* xref:usage.adoc[Usage]
+* xref:index.adoc[Overview]
+* xref:configuration.adoc[Configuration]
+* xref:usage.adoc[Usage]
diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc
@@ -0,0 +1,70 @@
+== Configuration
+
+The plugin is configured in your `pyproject.toml` file under `[tool.reqstool]`.
+
+=== Complete Configuration Example
+
+[source,toml]
+----
+[tool.poetry.dependencies]
+reqstool-python-decorators = "<version>"
+
+[tool.reqstool]
+# Directories to scan for decorators
+# Default: ["src", "tests"]
+sources = ["src", "tests"]
+
+# Test result file pattern(s)
+# Default: ["build/**/junit.xml"]
+test_results = ["build/**/junit.xml"]
+
+# Directory containing requirements.yml and optional files
+# Default: "docs/reqstool"
+dataset_directory = "docs/reqstool"
+
+# Output directory for generated annotations
+# Default: "build/reqstool"
+output_directory = "build/reqstool"
+----
+
+=== Configuration Parameters
+
+==== sources
+
+Directories to scan for `@Requirements` and `@SVCs` decorators.
+Defaults to `["src", "tests"]`.
+
+[source,toml]
+----
+sources = ["src", "tests"]
+----
+
+==== test_results
+
+Path or pattern(s) for test result files (JUnit XML).
+Defaults to `["build/**/junit.xml"]`.
+
+[source,toml]
+----
+test_results = ["build/**/junit.xml"]
+----
+
+==== dataset_directory
+
+Directory containing `requirements.yml` and optional reqstool files (`software_verification_cases.yml`, `manual_verification_results.yml`).
+Defaults to `"docs/reqstool"`.
+
+[source,toml]
+----
+dataset_directory = "docs/reqstool"
+----
+
+==== output_directory
+
+Output directory for the generated `annotations.yml`.
+Defaults to `"build/reqstool"`.
+
+[source,toml]
+----
+output_directory = "build/reqstool"
+----
diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -1,11 +1,57 @@
-= Reqstool Python Poetry Plugin
+= reqstool Python Poetry Plugin
 
-include::description.adoc[]
+WARNING: Poetry plugin support is currently untested. Functionality may be broken. Contributions welcome.
 
-include::installation.adoc[]
+This Poetry plugin generates annotations and assembles reqstool data during `poetry build` and `poetry install`. It collects decorated code using https://github.com/reqstool/reqstool-python-decorators[reqstool-python-decorators] and packages everything for consumption by the reqstool CLI.
 
-include::usage.adoc[]
+== Features
+
+* *Poetry integration*: Runs automatically during `poetry build` and `poetry install`
+* *Combines annotations*: Collects `@Requirements` and `@SVCs` decorators from source and test code
+* *Assembles package data*: Includes requirements, test results, and annotations in the built package
+* *Generates config*: Creates a `reqstool_config.yml` with correct paths for the package structure
+
+== Quick Start
+
+== Add the Plugin
+
+[source,bash]
+----
+poetry add --group dev reqstool-python-poetry-plugin
+----
+
+== Default Behavior
+
+When running `poetry build` the plugin will:
+
+1. Scan source and test directories for `@Requirements` and `@SVCs` decorators
+2. Generate an `annotations.yml` file in `build/reqstool/`
+3. Create a `reqstool_config.yml` in the project root for inclusion in the sdist
+4. Remove `reqstool_config.yml` from the project root after the build completes
+
+When running `poetry install` the plugin will update `pyproject.toml` with the necessary `include` entries so reqstool files are bundled into distributions.
+
+== Minimal Setup
+
+[source]
+----
+my-project/
+├── pyproject.toml
+├── docs/
+│   └── reqstool/
+│       └── requirements.yml  (mandatory)
+├── src/
+└── tests/
+----
+
+Run `poetry build` and the annotations will be generated automatically.
+
+== Prerequisites
+
+* Python 3.13+
+* https://python-poetry.org/[Poetry]
+* https://github.com/reqstool/reqstool-python-decorators[reqstool-python-decorators] as a project dependency
 
 == License
 
-This project is licensed under the MIT License - see the LICENSE.md file for details.
+MIT License.
diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc