docs: reduce custom code (#1173)

* docs: remove custom scripting in favor of native SBDL functionality

* docs: Update SRS template

* docs: fix artifact paths

* docs: change paths

* docs: homogonize titles

* docs: try to create a valid Gherkin SBDL hybrid

* docs: remove leftover from previous experiment

* docs: unconfuse Gherkin parser by commenting @sbdl-[begin|end]

The @sbdl markers were seen as tags

* docs: update all scenarios

* chore: disable megalinter built-in gherkin-lint

* ci: minor refactor of run steps

* docs: test different formatting

* docs: formatting changes

* Update compilation.feature

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Ron <45816308+rjaegers@users.noreply.github.com>

---------

Signed-off-by: Ron <45816308+rjaegers@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: rjaegers

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

@@ -23,17 +23,18 @@ jobs:
         run: |
           set -Eeuo pipefail
           sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
-          python -m pip install gherkin-official==35.1.0 sbdl==1.16.4
+          python -m pip install gherkin-official==38.0.0 sbdl==1.21.3
+      - name: Build & Validate SBDL model
+        run: sbdl -m compile test/cpp/features/*.feature > amp-devcontainer.sbdl
       - name: Generate SRS document
-        run: |
-          set -Eeuo pipefail
-          python docs/support/gherkin-to-sbdl.py test/cpp/features/*.feature
-          sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 output.sbdl > software-requirements-specification.md
-      - uses: docker://pandoc/extra:3.7.0@sha256:a703d335fa237f8fc3303329d87e2555dca5187930da38bfa9010fa4e690933a
+        run: sbdl -m template-fill --template docs/templates/software-requirements-specification.md.j2 amp-devcontainer.sbdl > software-requirements-specification.md
+      - uses: docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62
         with:
-          args: --template eisvogel --listings --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
+          args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
       - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: documents
-          path: "*.pdf"
+          path: |
+            *.pdf
+            *.sbdl
           retention-days: 2

.mega-linter.yml

@@ -1,7 +1,6 @@
 ENABLE:
   - ACTION
   - DOCKERFILE
-  - GHERKIN
   - JSON
   - MARKDOWN
   - REPOSITORY

docs/support/gherkin-to-sbdl.py

@@ -2,7 +2,7 @@
 title: "Software requirements specification for amp-devcontainer"
 author: ["@rjaegers"]
 colorlinks: true
-date: "October-2025"
+date: "February-2026"
 keywords: [Software, Requirements, SRS, amp-devcontainer]
 lang: "en"
 titlepage: true
@@ -46,24 +46,26 @@ The containers may be used both for local development and continuous integration
 {{ text.encode('utf-8').decode('unicode_escape') }}
 {%- endmacro -%}
 
-{%- macro sbdl_id_to_header(text) -%}
-{{ text.replace('_', ' ') }}
+{%- macro strip_gherkin_prefix(text) -%}
+{{ text | replace('Rule: ', '') | replace('Feature: ', '') }}
 {%- endmacro -%}
 
-{%- for req_id, requirement in sbdl.items() %}
-{%- if requirement.type == 'requirement' and 'parent' not in requirement %}
+{%- for aspect_id, aspect in sbdl.items() %}
+{%- if aspect.type == 'aspect' %}
 
-## {{ reencode(sbdl_id_to_header(req_id)) }}
+## {{ reencode(strip_gherkin_prefix(aspect['custom:title'])) }}
 
-{{ reencode(requirement.description) }}
+{{ reencode(aspect.description) }}
 
-{%- if 'child' in requirement %}
-{%- for child in requirement.child %}
-{%- set child_req = sbdl[child.identifier] %}
+{%- if 'requirement' in aspect %}
+{%- for req_ref in aspect.requirement %}
+{%- set req = sbdl[req_ref.identifier] %}
 
-### {{ reencode(sbdl_id_to_header(child.identifier)) }}
+### {{ req_ref.identifier }}: {{ reencode(strip_gherkin_prefix(req['custom:title'])) }}
 
-{{ reencode(child_req.description) }}
+{{ reencode(req.description) }}
+
+{{ reencode(req.remark) }}
 
 {%- endfor %}
 {%- endif %}