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..c24d679 100644 --- a/README.md +++ b/README.md @@ -1,88 +1,56 @@ - [![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 +## Prerequisites - Python >= 3.13 ## 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 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..592f00d 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,7 +1,12 @@ -= Reqstool Python Decorators += reqstool Python Decorators -include::description.adoc[] +This provides decorators and collecting of decorated code, formatting it and writing to yaml file. -include::installation.adoc[] +== Related components -include::licence.adoc[] \ No newline at end of file +* 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. diff --git a/docs/modules/ROOT/pages/installation.adoc b/docs/modules/ROOT/pages/installation.adoc index 499af4c..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 install: - -``` -$pip install reqstool-python-decorators -``` \ No newline at end of file +[source,bash] +---- +pip install reqstool-python-decorators +---- 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`. -