docs: reduce custom code

[Ron (rjaegers)]

🚀 Hey, I have created a Pull Request

Description of changes

This pull request makes significant improvements to the requirements documentation workflow and the structure of requirements in the project. It removes the custom Gherkin-to-SBDL Python tooling in favor of a more direct and maintainable approach using SBDL blocks within Gherkin feature files. The workflow for generating the Software Requirements Specification (SRS) document is updated to use these SBDL blocks, and the SRS template is adapted to better present the new structure. Additionally, some dependencies are updated, and minor configuration changes are made.

The most important changes are:

Requirements Documentation Workflow Modernization:

• Removed the custom Python scripts (gherkin-to-sbdl.py, gherkin_mapping_config.py, gherkin_sbdl_converter.py) for converting Gherkin to SBDL, simplifying the workflow and maintenance. [1] [2] [3]
• Updated the GitHub Actions workflow to directly compile .feature files containing SBDL blocks using the sbdl tool, eliminating the need for intermediate conversion scripts. Artifacts now include both .pdf and .sbdl outputs.

Requirements Structure and Content:

• Refactored all .feature files to include explicit SBDL blocks for aspects and requirements, providing clearer, more maintainable, and more expressive requirements definitions directly in the Gherkin files. [1] [2]

SRS Document Generation and Presentation:

• Updated the SRS template (software-requirements-specification.md.j2) to work with the new SBDL structure, including improved header formatting and better handling of aspects and requirements.
• Changed the SRS document date to "February-2026".

Dependency and Configuration Updates:

• Upgraded dependencies for gherkin-official and sbdl in the workflow, and updated the Pandoc Docker image version and arguments for improved PDF generation.
• Disabled the Gherkin linter in .mega-linter.yml, as it uses gherkin-lint which has not been updated for a while and does not understand the nested SBDL, which is valid Gherkin.

✔️ Checklist

• I have followed the contribution guidelines for this repository
• I have added tests for new behavior, and have not broken any existing tests
• I have added or updated relevant documentation
• I have verified that all added components are accounted for in the SBOM

[github-actions]

📦 Container Size Analysis

Note

Comparing ghcr.io/philips-software/amp-devcontainer-base:edge ➔ ghcr.io/philips-software/amp-devcontainer-base:pr-1173

📈 Size Comparison Table

OS/Platform	Previous	Current	Change	Trend
linux/amd64	175.16 MB	175.16 MB	+182 B (+0%)	🔼
linux/arm64	167.63 MB	167.63 MB	+43 B (+0%)	🔼

[github-actions]

✅⚠️MegaLinter analysis: Success with warnings

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ ACTION	actionlint	23		0	0	0.67s
✅ DOCKERFILE	hadolint	3		0	0	0.81s
✅ JSON	npm-package-json-lint	yes		no	no	0.52s
✅ JSON	prettier	21	4	0	0	0.55s
✅ JSON	v8r	21		0	0	7.43s
✅ MARKDOWN	markdownlint	12	0	0	0	1.38s
✅ MARKDOWN	markdown-table-formatter	12	0	0	0	0.23s
✅ REPOSITORY	checkov	yes		no	no	17.77s
✅ REPOSITORY	gitleaks	yes		no	no	0.61s
✅ REPOSITORY	git_diff	yes		no	no	0.01s
✅ REPOSITORY	grype	yes		no	no	30.66s
✅ REPOSITORY	secretlint	yes		no	no	0.93s
✅ REPOSITORY	syft	yes		no	no	1.99s
✅ REPOSITORY	trivy	yes		no	no	7.98s
✅ REPOSITORY	trivy-sbom	yes		no	no	0.23s
✅ REPOSITORY	trufflehog	yes		no	no	2.24s
⚠️ SPELL	lychee	83		7	0	21.78s
✅ YAML	prettier	31	0	0	0	1.04s
✅ YAML	v8r	31		0	0	9.56s
✅ YAML	yamllint	31		0	0	0.87s

Detailed Issues

⚠️ SPELL / lychee - 7 errors

[IGNORED] docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62 | Unsupported: Error creating request client: builder error for url (docker://pandoc/extra:3.9.0.0-ubuntu@sha256:72afa9c8d3300e5f10c9c4330e101725687f2179bffd912fb859c6d2ae85de62)
[403] https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads | Network error: Forbidden
[IGNORED] https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/philips-software/amp-devcontainer | Unsupported: Error creating request client: builder error for url (vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/philips-software/amp-devcontainer)
[429] https://github.com/philips-software/amp-devcontainer/blob/main/README.md | Network error: Too Many Requests
[429] https://github.com/opencontainers/image-spec/blob/main/spec.md | Network error: Too Many Requests
[429] https://github.com/philips-software/amp-devcontainer/blob/main/.github/CONTRIBUTING.md | Network error: Too Many Requests
[429] https://github.com/philips-software/amp-devcontainer/blob/main/README.md | Network error: Too Many Requests
[429] https://github.com/philips-software/amp-devcontainer/blob/main/LICENSE | Network error: Too Many Requests
[429] https://github.com/philips-software/amp-devcontainer/blob/main/LICENSE | Network error: Too Many Requests
📝 Summary
---------------------
🔍 Total..........126
✅ Successful.....117
⏳ Timeouts.........0
🔀 Redirected.......0
👻 Excluded.........0
❓ Unknown..........0
🚫 Errors...........7

Errors in .github/TOOL_VERSION_ISSUE_TEMPLATE.md
[403] https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads | Network error: Forbidden

Errors in templates/cpp/devcontainer-template.json
[429] https://github.com/philips-software/amp-devcontainer/blob/main/README.md | Network error: Too Many Requests
[429] https://github.com/philips-software/amp-devcontainer/blob/main/LICENSE | Network error: Too Many Requests

Errors in templates/rust/devcontainer-template.json
[429] https://github.com/philips-software/amp-devcontainer/blob/main/LICENSE | Network error: Too Many Requests
[429] https://github.com/philips-software/amp-devcontainer/blob/main/README.md | Network error: Too Many Requests

Errors in test/cpp/features/compatibility.feature
[429] https://github.com/opencontainers/image-spec/blob/main/spec.md | Network error: Too Many Requests

Errors in .github/PULL_REQUEST_TEMPLATE.md
[429] https://github.com/philips-software/amp-devcontainer/blob/main/.github/CONTRIBUTING.md | Network error: Too Many Requests

See detailed reports in MegaLinter artifacts

You could have the same capabilities but better runtime performances if you use a MegaLinter flavor:

• oxsecurity/megalinter/flavors/salesforce@v9.3.0 (58 linters)
• oxsecurity/megalinter/flavors/javascript@v9.3.0 (61 linters)

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

• Documentation: Custom Flavors
• Command: npx mega-linter-runner@9.3.0 --custom-flavor-setup --custom-flavor-linters ACTION_ACTIONLINT,DOCKERFILE_HADOLINT,JSON_V8R,JSON_PRETTIER,JSON_NPM_PACKAGE_JSON_LINT,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_GITLEAKS,REPOSITORY_GRYPE,REPOSITORY_SECRETLINT,REPOSITORY_SYFT,REPOSITORY_TRIVY,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,SPELL_LYCHEE,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

[Copilot]

Pull request overview

This PR updates the documentation generation pipeline to rely more directly on SBDL tooling (instead of custom Python conversion), embedding SBDL model content alongside existing Gherkin feature files.

Changes:

• Embed SBDL aspect/requirement declarations into compatibility.feature using @sbdl-begin / @sbdl-end blocks.
• Update the SRS Jinja template to render aspects and their referenced requirements from the SBDL model.
• Remove the custom Gherkin→SBDL Python conversion scripts and update the reusable document-generation workflow to compile via sbdl -m compile.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test/cpp/features/compatibility.feature	Adds embedded SBDL model blocks for compatibility requirements.
docs/templates/software-requirements-specification.md.j2	Adjusts template logic to render aspects + requirements from the compiled SBDL model.
docs/support/gherkin_sbdl_converter.py	Removes custom converter implementation.
docs/support/gherkin_mapping_config.py	Removes custom mapping configuration.
docs/support/gherkin-to-sbdl.py	Removes CLI wrapper for the custom converter.
.github/workflows/wc-document-generation.yml	Switches to sbdl -m compile and updates dependencies/artifacts for doc generation.

[github-actions]

📦 Container Size Analysis

Note

Comparing ghcr.io/philips-software/amp-devcontainer-rust:edge ➔ ghcr.io/philips-software/amp-devcontainer-rust:pr-1173

📈 Size Comparison Table

OS/Platform	Previous	Current	Change	Trend
linux/amd64	555.57 MB	555.57 MB	+145 B (+0%)	🔼
linux/arm64	509.75 MB	509.75 MB	114 B (0%)	🔽

[github-actions]

📦 Container Size Analysis

Note

Comparing ghcr.io/philips-software/amp-devcontainer-cpp:edge ➔ ghcr.io/philips-software/amp-devcontainer-cpp:pr-1173

📈 Size Comparison Table

OS/Platform	Previous	Current	Change	Trend
linux/amd64	696.88 MB	696.87 MB	1.09 kB (0%)	🔽
linux/arm64	677.68 MB	677.68 MB	697 B (0%)	🔽

[github-actions]

Test Results

 13 files  ±0   13 suites  ±0   19m 40s ⏱️ +3s
 33 tests ±0   33 ✅ ±0  0 💤 ±0  0 ❌ ±0 
137 runs  ±0  137 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 448729b. ± Comparison against base commit d7ff165.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

The Pandoc invocation uses --syntax-highlighting idiomatic, which doesn’t appear to be a valid Pandoc CLI option (Pandoc uses --highlight-style / --no-highlight, and --listings if you want LaTeX listings). As written, this step is likely to fail and block document generation; please switch to the correct Pandoc highlighting flag (and keep --listings if that behavior is still desired).

Suggested change

	args: --template eisvogel --syntax-highlighting idiomatic --number-sections --output software-requirements-specification.pdf software-requirements-specification.md
	args: --template eisvogel --highlight-style tango --number-sections --output software-requirements-specification.pdf software-requirements-specification.md