From b7cb2d45b788bf7b0c7bfd982aa4d35ab23b6316 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 15:25:40 +0100 Subject: [PATCH 1/5] 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 --- .github/workflows/publish_gh_pages.yml | 47 ------------------ CONTRIBUTING.md | 25 ++++++++++ README.md | 66 +++++++------------------- docs/antora-playbook.yml | 1 + 4 files changed, 43 insertions(+), 96 deletions(-) delete mode 100644 .github/workflows/publish_gh_pages.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/publish_gh_pages.yml b/.github/workflows/publish_gh_pages.yml deleted file mode 100644 index 49df3d4..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..2a1ab2b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,25 @@ +# Contributing to reqstool-python-decorators + +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+ +- [Hatch](https://hatch.pypa.io/) (`pip install hatch`) + +## Setup + +```bash +git clone https://github.com/reqstool/reqstool-python-decorators.git +cd reqstool-python-decorators +hatch env create +``` + +## Build & Test + +```bash +hatch build +hatch run test +``` diff --git a/README.md b/README.md index cfc7b05..1ef2496 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,12 @@ - [![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-python-decorators?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-python-decorators/pulse) [![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-python-decorators?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-python-decorators/issues) [![License](https://img.shields.io/github/license/reqstool/reqstool-python-decorators?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/) [![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-python-decorators/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-python-decorators/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-decorators/reqstool-python-decorators/0.0.1/index.html) +[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io) # Reqstool Python Decorators -## Description - -This provides decorators and collecting of decorated code, formatting it and writing to yaml file. +Python decorators for [reqstool](https://github.com/reqstool/reqstool-client) requirements traceability. Provides `@Requirements` and `@SVCs` decorators for linking Python code to requirements and software verification cases. ## Requirements @@ -17,72 +14,43 @@ This provides decorators and collecting of decorated code, formatting it and wri ## Installation -The package name is `reqstool-python-decorators`. - -* Using pip install: - -``` -$pip install reqstool-python-decorators +```bash +pip install reqstool-python-decorators ``` ## Usage -### pyproject.toml - -* Hatch - -``` -dependencies = [ - "reqstool-python-decorators == " -] -``` - -* Poetry - -``` -[tool.poetry.dependencies] -reqstool-python-decorators = "" -``` - -### Decorators - -Import decorators: - -``` +```python from reqstool_python_decorators.decorators.decorators import Requirements, SVCs -``` - -Example usage of the decorators: -``` @Requirements("REQ_111", "REQ_222") def somefunction(): -``` + pass -``` @SVCs("SVC_111", "SVC_222") def test_somefunction(): + pass ``` ### Processor -Import processor: - -``` +```python from reqstool_python_decorators.processors.decorator_processor import DecoratorProcessor -``` - -Main function to collect decorators data and generate yaml file: -``` +# Collect decorators and generate annotations.yml process_decorated_data(path_to_python_files, output_file) ``` -`path_to_python_files` is the directories to search through to find decorated code. +Used together with the [Hatch Plugin](https://github.com/reqstool/reqstool-python-hatch-plugin) or [Poetry Plugin](https://github.com/reqstool/reqstool-python-poetry-plugin). + +## Documentation + +Full documentation can be found [here](https://reqstool.github.io). -(Optional) `output_file` is output file(path) the yaml file is stored to. Default is `/build/reqstool/annotations.yml`. +## 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 06fa073..72c83c9 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 Decorators Documentation From 833f4edb99efcc5b7fe5b563ed1779fe9901c80e Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 16:19:00 +0100 Subject: [PATCH 2/5] docs: rename Requirements to Prerequisites, fix shell prompt Signed-off-by: jimisola --- README.md | 2 +- docs/modules/ROOT/pages/installation.adoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1ef2496..c24d679 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Python decorators for [reqstool](https://github.com/reqstool/reqstool-client) requirements traceability. Provides `@Requirements` and `@SVCs` decorators for linking Python code to requirements and software verification cases. -## Requirements +## Prerequisites - Python >= 3.13 diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index 499af4c..fb1f1cb 100644 --- a/docs/modules/ROOT/pages/installation.adoc +++ b/docs/modules/ROOT/pages/installation.adoc @@ -2,8 +2,8 @@ The package name is `reqstool-python-decorators`. -* Using pip install: +* Using pip: ``` -$pip install reqstool-python-decorators +pip install reqstool-python-decorators ``` \ No newline at end of file From 62ed396fb861cdcb2be2cb4ecae44bb78de609c5 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 16:42:14 +0100 Subject: [PATCH 3/5] docs: streamline nav and page structure - Separate nav items instead of single include-based page - Merge description.adoc content into index.adoc - Remove licence.adoc, add inline license to index.adoc - Fix markdown fenced blocks to AsciiDoc source blocks - Add installation.adoc to nav - Change nav label from Start to Overview Signed-off-by: jimisola --- docs/modules/ROOT/nav.adoc | 5 ++-- docs/modules/ROOT/pages/description.adoc | 3 -- docs/modules/ROOT/pages/index.adoc | 6 ++-- docs/modules/ROOT/pages/installation.adoc | 7 ++--- docs/modules/ROOT/pages/licence.adoc | 3 -- docs/modules/ROOT/pages/usage.adoc | 36 +++++++++++++---------- 6 files changed, 30 insertions(+), 30 deletions(-) delete mode 100644 docs/modules/ROOT/pages/description.adoc delete mode 100644 docs/modules/ROOT/pages/licence.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index ccbcafa..3eadec5 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,2 +1,3 @@ -* xref:index.adoc[Start] -* xref:usage.adoc[Usage] \ No newline at end of file +* xref:index.adoc[Overview] +* xref:installation.adoc[Installation] +* xref:usage.adoc[Usage] diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc deleted file mode 100644 index 0342c11..0000000 --- a/docs/modules/ROOT/pages/description.adoc +++ /dev/null @@ -1,3 +0,0 @@ -== Description - -This provides decorators and collecting of decorated code, formatting it and writing to yaml file. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 499aaa5..7ded47e 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,7 +1,7 @@ = Reqstool Python Decorators -include::description.adoc[] +This provides decorators and collecting of decorated code, formatting it and writing to yaml file. -include::installation.adoc[] +== License -include::licence.adoc[] \ No newline at end of file +MIT License. diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index fb1f1cb..c1b4b0a 100644 --- a/docs/modules/ROOT/pages/installation.adoc +++ b/docs/modules/ROOT/pages/installation.adoc @@ -2,8 +2,7 @@ The package name is `reqstool-python-decorators`. -* Using pip: - -``` +[source,bash] +---- pip install reqstool-python-decorators -``` \ No newline at end of file +---- diff --git a/docs/modules/ROOT/pages/licence.adoc b/docs/modules/ROOT/pages/licence.adoc deleted file mode 100644 index c7b1e71..0000000 --- a/docs/modules/ROOT/pages/licence.adoc +++ /dev/null @@ -1,3 +0,0 @@ -== License - -This project is licensed under the MIT License - see the LICENSE.md file for details. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index e9175e6..e505174 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -4,54 +4,60 @@ * Hatch -``` +[source,toml] +---- dependencies = [ "reqstool-python-decorators == " ] -``` +---- * Poetry -``` +[source,toml] +---- [tool.poetry.dependencies] reqstool-python-decorators = "" -``` +---- === Decorators Import decorators: -``` +[source,python] +---- from reqstool_python_decorators.decorators.decorators import Requirements, SVCs -``` +---- Example usage of the decorators: -```python +[source,python] +---- @Requirements("REQ_111", "REQ_222") def somefunction(): -``` +---- -```python +[source,python] +---- @SVCs("SVC_111", "SVC_222") def test_somefunction(): -``` +---- === Processor Import processor: -``` +[source,python] +---- from reqstool_python_decorators.processors.decorator_processor import DecoratorProcessor -``` +---- Main function to collect decorators data and generate yaml file: -``` +[source,python] +---- process_decorated_data(path_to_python_files, output_file) -``` +---- `path_to_python_files` is the directories to search through to find decorated code. (Optional) `output_file` is output file(path) the yaml file is stored to. Default is `/build/reqstool/annotations.yml`. - From 81d466e9d67dcbd570f8f7bc69da5a22cbcb292d Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 18:43:12 +0100 Subject: [PATCH 4/5] docs: use lowercase reqstool consistently Signed-off-by: jimisola --- docs/modules/ROOT/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 7ded47e..fe633aa 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,4 +1,4 @@ -= Reqstool Python Decorators += reqstool Python Decorators This provides decorators and collecting of decorated code, formatting it and writing to yaml file. From bad9cda22fda8566cabfc67f2f3e8aa211465a26 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 19:08:07 +0100 Subject: [PATCH 5/5] docs: add cross-component xrefs to Hatch and Poetry plugins Signed-off-by: jimisola --- docs/modules/ROOT/pages/index.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index fe633aa..592f00d 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -2,6 +2,11 @@ This provides decorators and collecting of decorated code, formatting it and writing to yaml file. +== Related components + +* xref:reqstool-python-hatch-plugin::index.adoc[Hatch Plugin] -- packages decorators output into a reqstool artifact during Hatch builds +* xref:reqstool-python-poetry-plugin::index.adoc[Poetry Plugin] -- packages decorators output into a reqstool artifact during Poetry builds + == License MIT License.