diff --git a/.github/workflows/publish_gh_pages.yml b/.github/workflows/publish_gh_pages.yml deleted file mode 100644 index 11a457d..0000000 --- a/.github/workflows/publish_gh_pages.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: Publish to GitHub Pages -on: - workflow_dispatch: - release: - types: [created] - push: - branches: - - main - -concurrency: - group: github-pages - cancel-in-progress: false -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write -jobs: - publish_gh_pages: - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Checkout repository - uses: actions/checkout@v6 - - name: Configure Pages - uses: actions/configure-pages@v5 - - name: Install Node.js - uses: actions/setup-node@v6 - with: - node-version: "24" - - name: Install Antora - run: npm i antora - - name: Install Asciidoctor Kroki extension - run: npm i asciidoctor asciidoctor-kroki - - name: Generate Site - run: npx antora docs/antora-playbook.yml - - name: Create site folders - run: mkdir -p docs/build/site - - name: Upload Artifacts - uses: actions/upload-pages-artifact@v4 - with: - path: docs/build/site - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6a19108 --- /dev/null +++ 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 index 12acb4a..7a9ee78 100644 --- 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 = "" +```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 index 53e60f6..cf220c3 100644 --- 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 index 0ed7914..cfb3122 100644 --- 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] \ No newline at end of file +* 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 new file mode 100644 index 0000000..46600a7 --- /dev/null +++ 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 = "" + +[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 deleted file mode 100644 index c4328c8..0000000 --- a/docs/modules/ROOT/pages/description.adoc +++ /dev/null @@ -1,7 +0,0 @@ -== Description - -WARNING: Poetry plugin support is currently untested. Functionality may be broken. Contributions welcome. - -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. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index f1a7c46..a13ec3d 100644 --- 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. \ No newline at end of file +MIT License. diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc deleted file mode 100644 index ea983bb..0000000 --- a/docs/modules/ROOT/pages/installation.adoc +++ /dev/null @@ -1,42 +0,0 @@ -== Installation - -=== Plugin - -The package name is `reqstool-python-poetry-plugin`. - -* Using poetry: - -``` -$poetry add 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 = "" -``` - -==== Configuration - -The plugin is configured in the `pyproject.toml` file. - -```toml -[tool.reqstool] -sources = ["src", "tests"] -test_results = ["build/**/junit.xml"] -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`. diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index 0787843..ad8d0b2 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -1,33 +1,47 @@ == Usage -=== Decorators +=== Basic Usage -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. +Add the plugin and configure it in your `pyproject.toml`: -Import decorators: +[source,toml] +---- +[tool.poetry.dependencies] +reqstool-python-decorators = "" -``` -from reqstool_python_decorators.decorators.decorators import Requirements, SVCs -``` +[tool.reqstool] +sources = ["src", "tests"] +test_results = ["build/**/junit.xml"] +dataset_directory = "docs/reqstool" +output_directory = "build/reqstool" +---- -Example usage of the decorators: +=== Decorator Dependency -``` -@Requirements("REQ_111", "REQ_222") -def somefunction(): -``` +To use `@Requirements` and `@SVCs` decorators in your code, add the decorators package as a dependency: -``` -@SVCs("SVC_111", "SVC_222") -def test_somefunction(): -``` +[source,toml] +---- +[tool.poetry.dependencies] +reqstool-python-decorators = "" +---- -=== Poetry Build +See https://github.com/reqstool/reqstool-python-decorators[reqstool-python-decorators] for decorator usage. -When running `$poetry build` the plugin will: +=== Running the Build -1. Generate an `annotations.yml` file in the `build/reqstool/` folder containing formatted data on all decorated code found. -2. Generate a `reqstool_config.yml` in the project root for inclusion in the sdist. -3. Remove `reqstool_config.yml` from the project root after the build completes. +[source,bash] +---- +poetry build +---- -When running `$poetry install` the plugin will update `pyproject.toml` with the necessary `include` entries so reqstool files are bundled into distributions. +=== Default Lifecycle + +The plugin integrates into the Poetry build process: + +1. `poetry build` is invoked +2. The plugin scans `sources` directories for decorated code +3. An `annotations.yml` is generated in the `output_directory` +4. A `reqstool_config.yml` is created in the project root for sdist inclusion +5. reqstool data is included in the built package +6. The temporary `reqstool_config.yml` is removed after the build completes