Skip to content

Commit b44f9c8

Browse files
rjaegersrjaegers
committed
docs: process review comments
1 parent 725e9f7 commit b44f9c8

5 files changed

Lines changed: 51 additions & 65 deletions

File tree

‎.github/workflows/wc-document-generation.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ on:
55
workflow_call:
66
inputs:
77
is-release:
8+
description: Whether the workflow is running for a release.
89
default: false
910
type: boolean
1011

‎docs/templates/partials/text-utilities.j2‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{% macro reencode(text) -%}
2+
{{ text.encode('utf-8').decode('unicode_escape') }}
3+
{%- endmacro -%}
4+
5+
{%- macro strip_gherkin_prefix(text) -%}
6+
{{ text | replace('Rule: ', '') | replace('Feature: ', '') }}
7+
{%- endmacro -%}
8+
9+
{%- macro strip_bats_syntax(text) -%}
10+
{{ text | replace('@test "', '') | replace('" \{', '') | replace('" {', '') }}
11+
{%- endmacro -%}
12+
13+
{%- macro display_short(text) -%}
14+
{{ text[:60] }}
15+
{%- endmacro %}

‎docs/templates/requirements-traceability-matrix.md.j2‎

Lines changed: 12 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,13 @@ toc: true
1414
toc-own-page: true
1515
header-includes:
1616
- \AtEndDocument{\label{lastpage}}
17-
{% if sbdl['doc_control']['custom:is_release'] != 'true' %}
17+
{%- if sbdl['doc_control']['custom:is_release'] != 'true' %}
1818
watermark: "DRAFT"
19-
{% endif %}
19+
{%- endif %}
2020
footer-right: "\\thepage \\hspace{1pt} of \\pageref*{lastpage}"
2121
...
2222

23-
{% macro reencode(text) -%}
24-
{{ text.encode('utf-8').decode('unicode_escape') }}
25-
{%- endmacro -%}
26-
27-
{%- macro strip_gherkin_prefix(text) -%}
28-
{{ text | replace('Rule: ', '') | replace('Feature: ', '') }}
29-
{%- endmacro -%}
30-
31-
{%- macro strip_bats_syntax(text) -%}
32-
{{ text | replace('@test "', '') | replace('" \{', '') | replace('" {', '') }}
33-
{%- endmacro -%}
34-
35-
{%- macro display_short(text) -%}
36-
{{ text[:60] }}
37-
{%- endmacro %}
23+
{% import "partials/text-utilities.j2" as utils %}
3824

3925
# Introduction
4026

@@ -54,18 +40,18 @@ This document is generated from a formal model defined in [sbdl](https://sbdl.de
5440
The authoritative source of change history is the [Git log](https://github.com/philips-software/amp-devcontainer/commits/) of the source material from which the model is built.
5541

5642
# Traceability Matrix
57-
{%- for aspect_id, aspect in sbdl.items() %}
58-
{%- if aspect.type == 'aspect' %}
43+
{%- for id, item in sbdl.items() %}
44+
{%- if item.type == 'aspect' and 'custom:title' in item %}
5945

60-
## {{ reencode(strip_gherkin_prefix(aspect['custom:title'])) }}
46+
## {{ utils.reencode(utils.strip_gherkin_prefix(item['custom:title'])) }}
6147

6248
| Requirement | Test | Status |
6349
|-------------|------|--------|
6450

65-
{%- if 'requirement' in aspect %}
66-
{%- for req_ref in aspect.requirement %}
51+
{%- if 'requirement' in item %}
52+
{%- for req_ref in item.requirement %}
6753
{%- set req = sbdl[req_ref.identifier] %}
68-
{%- set req_name = reencode(strip_gherkin_prefix(req['custom:title'])) | trim %}
54+
{%- set req_name = utils.reencode(utils.strip_gherkin_prefix(req['custom:title'])) | trim %}
6955

7056
{%- set ns_tests = namespace(test_list=[]) -%}
7157

@@ -81,11 +67,11 @@ The authoritative source of change history is the [Git log](https://github.com/p
8167

8268
{%- if ns_tests.test_list -%}
8369
{%- for test_id in ns_tests.test_list %}
84-
{%- set test_name = strip_bats_syntax(strip_gherkin_prefix(sbdl[test_id]['custom:title'])) | trim %}
85-
| {{ display_short(req_name) }} | {{ test_id }}: {{ display_short(test_name) | capitalize }} | Traced |
70+
{%- set test_name = utils.strip_bats_syntax(sbdl[test_id]['custom:title']) | trim %}
71+
| {{ utils.display_short(req_name) }} | {{ test_id }}: {{ utils.display_short(test_name) | capitalize }} | Traced |
8672
{%- endfor -%}
8773
{%- else %}
88-
| {{ display_short(req_name) }} | — | **Not covered** |
74+
| {{ utils.display_short(req_name) }} | — | **Not covered** |
8975
{%- endif -%}
9076

9177
{%- endfor %}

‎docs/templates/software-requirements-specification.md.j2‎

Lines changed: 13 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,14 @@ toc: true
1414
toc-own-page: true
1515
header-includes:
1616
- \AtEndDocument{\label{lastpage}}
17-
{% if sbdl['doc_control']['custom:is_release'] != 'true' %}
17+
{%- if sbdl['doc_control']['custom:is_release'] != 'true' %}
1818
watermark: "DRAFT"
19-
{% endif %}
19+
{%- endif %}
2020
footer-right: "\\thepage \\hspace{1pt} of \\pageref*{lastpage}"
2121
...
2222

23+
{% import "partials/text-utilities.j2" as utils %}
24+
2325
# Introduction
2426

2527
## Purpose
@@ -85,30 +87,22 @@ The containers may be used both for local development and continuous integration
8587

8688
# Requirements
8789

88-
{%- macro reencode(text) -%}
89-
{{ text.encode('utf-8').decode('unicode_escape') }}
90-
{%- endmacro -%}
91-
92-
{%- macro strip_gherkin_prefix(text) -%}
93-
{{ text | replace('Rule: ', '') | replace('Feature: ', '') }}
94-
{%- endmacro -%}
95-
96-
{%- for aspect_id, aspect in sbdl.items() %}
97-
{%- if aspect.type == 'aspect' %}
90+
{%- for id, item in sbdl.items() %}
91+
{%- if item.type == 'aspect' and 'custom:title' in item %}
9892

99-
## {{ reencode(strip_gherkin_prefix(aspect['custom:title'])) }}
93+
## {{ utils.reencode(utils.strip_gherkin_prefix(item['custom:title'])) }}
10094

101-
{{ reencode(aspect.description) }}
95+
{{ utils.reencode(item.description) }}
10296

103-
{%- if 'requirement' in aspect %}
104-
{%- for req_ref in aspect.requirement %}
97+
{%- if 'requirement' in item %}
98+
{%- for req_ref in item.requirement %}
10599
{%- set req = sbdl[req_ref.identifier] %}
106100

107-
### {{ req_ref.identifier }}: {{ reencode(strip_gherkin_prefix(req['custom:title'])) }}
101+
### {{ req_ref.identifier }}: {{ utils.reencode(utils.strip_gherkin_prefix(req['custom:title'])) }}
108102

109-
{{ reencode(req.description) }}
103+
{{ utils.reencode(req.description) }}
110104

111-
{{ reencode(req.remark) }}
105+
{{ utils.reencode(req.remark) }}
112106

113107
{%- endfor %}
114108
{%- endif %}

‎docs/templates/software-test-plan.md.j2‎

Lines changed: 10 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -14,23 +14,13 @@ toc: true
1414
toc-own-page: true
1515
header-includes:
1616
- \AtEndDocument{\label{lastpage}}
17-
{% if sbdl['doc_control']['custom:is_release'] != 'true' %}
17+
{%- if sbdl['doc_control']['custom:is_release'] != 'true' %}
1818
watermark: "DRAFT"
19-
{% endif %}
19+
{%- endif %}
2020
footer-right: "\\thepage \\hspace{1pt} of \\pageref*{lastpage}"
2121
...
2222

23-
{% macro reencode(text) -%}
24-
{{ text.encode('utf-8').decode('unicode_escape') }}
25-
{%- endmacro -%}
26-
27-
{%- macro strip_gherkin_prefix(text) -%}
28-
{{ text | replace('Rule: ', '') | replace('Feature: ', '') }}
29-
{%- endmacro %}
30-
31-
{%- macro strip_bats_syntax(text) -%}
32-
{{ text | replace('@test "', '') | replace('" \{', '') | replace('" {', '') }}
33-
{%- endmacro -%}
23+
{% import "partials/text-utilities.j2" as utils %}
3424

3525
# Introduction
3626

@@ -94,16 +84,16 @@ BATS tests verify tool presence, version alignment, and end-to-end workflows (co
9484
> **Note**: Structured expected-result data per test is not yet available in the current toolchain. This section will be extended when test result rendering is implemented. Currently, a test is considered passed when it completes without error as described above.
9585

9686
# Tests by requirement area
97-
{%- for aspect_id, aspect in sbdl.items() %}
98-
{%- if aspect.type == 'aspect' %}
87+
{%- for id, item in sbdl.items() %}
88+
{%- if item.type == 'aspect' and 'custom:title' in item %}
9989

100-
## {{ reencode(strip_gherkin_prefix(aspect['custom:title'])) }}
90+
## {{ utils.reencode(utils.strip_gherkin_prefix(item['custom:title'])) }}
10191

102-
{%- if 'requirement' in aspect %}
103-
{%- for req_ref in aspect.requirement %}
92+
{%- if 'requirement' in item %}
93+
{%- for req_ref in item.requirement %}
10494
{%- set req = sbdl[req_ref.identifier] %}
10595

106-
### {{ req_ref.identifier }}: {{ reencode(strip_gherkin_prefix(req['custom:title'])) }}
96+
### {{ req_ref.identifier }}: {{ utils.reencode(utils.strip_gherkin_prefix(req['custom:title'])) }}
10797

10898
{%- set ns_tests = namespace(has_tests=false) -%}
10999

@@ -112,7 +102,7 @@ BATS tests verify tool presence, version alignment, and end-to-end workflows (co
112102
{%- if 'requirement' in test_elem -%}
113103
{%- for test_req_ref in test_elem.requirement if test_req_ref.identifier == req_ref.identifier -%}
114104
{%- set ns_tests.has_tests = true %}
115-
- **{{ test_id }}**: {{ reencode(strip_bats_syntax(test_elem['custom:title'])) | capitalize }}
105+
- **{{ test_id }}**: {{ utils.reencode(utils.strip_bats_syntax(test_elem['custom:title'])) | capitalize }}
116106
{%- endfor -%}
117107
{%- endif -%}
118108
{%- endif -%}

0 commit comments

Comments
 (0)