Skip to content

Commit ae85ceb

Browse files
jimisolaJimisola Laursen
jimisola
and
Jimisola Laursen
authored
docs: documentation overhaul (#73)
* 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: rename Requirements to Prerequisites, fix shell prompt Signed-off-by: jimisola <jimisola@jimisola.com> * 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 <jimisola@jimisola.com> * docs: use lowercase reqstool consistently Signed-off-by: jimisola <jimisola@jimisola.com> * docs: add cross-component xrefs to Hatch and Poetry plugins Signed-off-by: jimisola <jimisola@jimisola.com> --------- Signed-off-by: jimisola <jimisola@jimisola.com> Co-authored-by: Jimisola Laursen <jimisola.laursen@resurs.se>
1 parent 34fb37e commit ae85ceb

10 files changed

Lines changed: 81 additions & 129 deletions

File tree

‎.github/workflows/publish_gh_pages.yml‎

Lines changed: 0 additions & 47 deletions
This file was deleted.

‎CONTRIBUTING.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Contributing to reqstool-python-decorators
2+
3+
Thank you for your interest in contributing!
4+
5+
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).
6+
7+
## Prerequisites
8+
9+
- Python 3.13+
10+
- [Hatch](https://hatch.pypa.io/) (`pip install hatch`)
11+
12+
## Setup
13+
14+
```bash
15+
git clone https://github.com/reqstool/reqstool-python-decorators.git
16+
cd reqstool-python-decorators
17+
hatch env create
18+
```
19+
20+
## Build & Test
21+
22+
```bash
23+
hatch build
24+
hatch run test
25+
```

‎README.md‎

Lines changed: 18 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,56 @@
1-
21
[![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)
32
[![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)
43
[![License](https://img.shields.io/github/license/reqstool/reqstool-python-decorators?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/)
54
[![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)
6-
[![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)
5+
[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io)
76

87
# Reqstool Python Decorators
98

10-
## Description
11-
12-
This provides decorators and collecting of decorated code, formatting it and writing to yaml file.
9+
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.
1310

14-
## Requirements
11+
## Prerequisites
1512

1613
- Python >= 3.13
1714

1815
## Installation
1916

20-
The package name is `reqstool-python-decorators`.
21-
22-
* Using pip install:
23-
24-
```
25-
$pip install reqstool-python-decorators
17+
```bash
18+
pip install reqstool-python-decorators
2619
```
2720

2821
## Usage
2922

30-
### pyproject.toml
31-
32-
* Hatch
33-
34-
```
35-
dependencies = [
36-
"reqstool-python-decorators == <version>"
37-
]
38-
```
39-
40-
* Poetry
41-
42-
```
43-
[tool.poetry.dependencies]
44-
reqstool-python-decorators = "<version>"
45-
```
46-
47-
### Decorators
48-
49-
Import decorators:
50-
51-
```
23+
```python
5224
from reqstool_python_decorators.decorators.decorators import Requirements, SVCs
53-
```
54-
55-
Example usage of the decorators:
5625

57-
```
5826
@Requirements("REQ_111", "REQ_222")
5927
def somefunction():
60-
```
28+
pass
6129

62-
```
6330
@SVCs("SVC_111", "SVC_222")
6431
def test_somefunction():
32+
pass
6533
```
6634

6735
### Processor
6836

69-
Import processor:
70-
71-
```
37+
```python
7238
from reqstool_python_decorators.processors.decorator_processor import DecoratorProcessor
73-
```
74-
75-
Main function to collect decorators data and generate yaml file:
7639

77-
```
40+
# Collect decorators and generate annotations.yml
7841
process_decorated_data(path_to_python_files, output_file)
7942
```
8043

81-
`path_to_python_files` is the directories to search through to find decorated code.
44+
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).
45+
46+
## Documentation
47+
48+
Full documentation can be found [here](https://reqstool.github.io).
8249

83-
(Optional) `output_file` is output file(path) the yaml file is stored to. Default is `/build/reqstool/annotations.yml`.
50+
## Contributing
8451

52+
See the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md).
8553

8654
## License
8755

88-
This project is licensed under the MIT License - see the LICENSE.md file for details.
56+
MIT License.

‎docs/antora-playbook.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json
2+
# For local development only. Published site: https://reqstool.github.io
23

34
site:
45
title: Reqstool Python Decorators Documentation

‎docs/modules/ROOT/nav.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
1-
* xref:index.adoc[Start]
2-
* xref:usage.adoc[Usage]
1+
* xref:index.adoc[Overview]
2+
* xref:installation.adoc[Installation]
3+
* xref:usage.adoc[Usage]

‎docs/modules/ROOT/pages/description.adoc‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/modules/ROOT/pages/index.adoc‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
1-
= Reqstool Python Decorators
1+
= reqstool Python Decorators
22

3-
include::description.adoc[]
3+
This provides decorators and collecting of decorated code, formatting it and writing to yaml file.
44

5-
include::installation.adoc[]
5+
== Related components
66

7-
include::licence.adoc[]
7+
* xref:reqstool-python-hatch-plugin::index.adoc[Hatch Plugin] -- packages decorators output into a reqstool artifact during Hatch builds
8+
* xref:reqstool-python-poetry-plugin::index.adoc[Poetry Plugin] -- packages decorators output into a reqstool artifact during Poetry builds
9+
10+
== License
11+
12+
MIT License.

‎docs/modules/ROOT/pages/installation.adoc‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@
22

33
The package name is `reqstool-python-decorators`.
44

5-
* Using pip install:
6-
7-
```
8-
$pip install reqstool-python-decorators
9-
```
5+
[source,bash]
6+
----
7+
pip install reqstool-python-decorators
8+
----

‎docs/modules/ROOT/pages/licence.adoc‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/modules/ROOT/pages/usage.adoc‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,54 +4,60 @@
44

55
* Hatch
66

7-
```
7+
[source,toml]
8+
----
89
dependencies = [
910
"reqstool-python-decorators == <version>"
1011
]
11-
```
12+
----
1213

1314
* Poetry
1415

15-
```
16+
[source,toml]
17+
----
1618
[tool.poetry.dependencies]
1719
reqstool-python-decorators = "<version>"
18-
```
20+
----
1921

2022
=== Decorators
2123

2224
Import decorators:
2325

24-
```
26+
[source,python]
27+
----
2528
from reqstool_python_decorators.decorators.decorators import Requirements, SVCs
26-
```
29+
----
2730

2831
Example usage of the decorators:
2932

30-
```python
33+
[source,python]
34+
----
3135
@Requirements("REQ_111", "REQ_222")
3236
def somefunction():
33-
```
37+
----
3438

35-
```python
39+
[source,python]
40+
----
3641
@SVCs("SVC_111", "SVC_222")
3742
def test_somefunction():
38-
```
43+
----
3944

4045
=== Processor
4146

4247
Import processor:
4348

44-
```
49+
[source,python]
50+
----
4551
from reqstool_python_decorators.processors.decorator_processor import DecoratorProcessor
46-
```
52+
----
4753

4854
Main function to collect decorators data and generate yaml file:
4955

50-
```
56+
[source,python]
57+
----
5158
process_decorated_data(path_to_python_files, output_file)
52-
```
59+
----
5360

5461
`path_to_python_files` is the directories to search through to find decorated code.
5562

5663
(Optional) `output_file` is output file(path) the yaml file is stored to. Default is `/build/reqstool/annotations.yml`.
57-

0 commit comments

Comments
 (0)