From 35c4b47850097f801e9e40cd577dc5ea15b9fa53 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Mon, 23 Jun 2025 12:29:24 +0000
Subject: [PATCH 01/13] chore: establish a basic structure for document
 generation

---
 .github/workflows/continuous-integration.yml |  4 +++
 .github/workflows/wc-document-generation.yml | 27 ++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 .github/workflows/wc-document-generation.yml

diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
index 5f9f7f84..8c19c378 100644
--- a/.github/workflows/continuous-integration.yml
+++ b/.github/workflows/continuous-integration.yml
@@ -25,3 +25,7 @@ jobs:
       id-token: write
       packages: write
       pull-requests: write
+  document-generation:
+    uses: ./.github/workflows/wc-document-generation.yml
+    permissions:
+      contents: read
diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
new file mode 100644
index 00000000..68255e09
--- /dev/null
+++ b/.github/workflows/wc-document-generation.yml
@@ -0,0 +1,27 @@
+---
+name: Document Generation
+
+on:
+  workflow_call:
+    inputs:
+      flavor:
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  generate-documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
+        with:
+          disable-sudo-and-containers: true
+          egress-policy: audit
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - run: |
+          set -Eeuo pipefail
+          python -m pip install gherkin-official https://sbdl.dev/sbdl-package.tar.gz

From 971710ed9d5630fc935db3a5a95a2e7dfd85522c Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Mon, 23 Jun 2025 12:57:45 +0000
Subject: [PATCH 02/13] chore: playing around with location and granularity

---
 .github/workflows/continuous-integration.yml | 4 ----
 .github/workflows/wc-build-push-test.yml     | 5 +++++
 .github/workflows/wc-document-generation.yml | 4 ----
 3 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml
index 8c19c378..5f9f7f84 100644
--- a/.github/workflows/continuous-integration.yml
+++ b/.github/workflows/continuous-integration.yml
@@ -25,7 +25,3 @@ jobs:
       id-token: write
       packages: write
       pull-requests: write
-  document-generation:
-    uses: ./.github/workflows/wc-document-generation.yml
-    permissions:
-      contents: read
diff --git a/.github/workflows/wc-build-push-test.yml b/.github/workflows/wc-build-push-test.yml
index d247d218..a79c6c4f 100644
--- a/.github/workflows/wc-build-push-test.yml
+++ b/.github/workflows/wc-build-push-test.yml
@@ -88,3 +88,8 @@ jobs:
       - uses: EnricoMi/publish-unit-test-result-action@3a74b2957438d0b6e2e61d67b05318aa25c9e6c6 # v2.20.0
         with:
           files: test-report-*.xml
+
+  generate-documents:
+    uses: ./.github/workflows/wc-document-generation.yml
+    permissions:
+      contents: read
diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index 68255e09..3c804ece 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -3,10 +3,6 @@ name: Document Generation
 
 on:
   workflow_call:
-    inputs:
-      flavor:
-        required: true
-        type: string
 
 permissions:
   contents: read

From 4781fa6bc5d04b894167871e2c591f72a9a80691 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Tue, 24 Jun 2025 05:31:18 +0000
Subject: [PATCH 03/13] chore: add gherkin extraction

---
 .github/workflows/wc-document-generation.yml |  4 ++
 docs/support/gherkin-to-csv.py               | 75 ++++++++++++++++++++
 test/cpp/features/compilation.feature        | 38 ++++++++--
 3 files changed, 111 insertions(+), 6 deletions(-)
 create mode 100755 docs/support/gherkin-to-csv.py

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index 3c804ece..fb57e51a 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -21,3 +21,7 @@ jobs:
       - run: |
           set -Eeuo pipefail
           python -m pip install gherkin-official https://sbdl.dev/sbdl-package.tar.gz
+      - run: |
+          set -Eeuo pipefail
+          python docs/support/gherkin-to-csv.py test/cpp/features/*.feature
+          python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv
diff --git a/docs/support/gherkin-to-csv.py b/docs/support/gherkin-to-csv.py
new file mode 100755
index 00000000..d2e71da7
--- /dev/null
+++ b/docs/support/gherkin-to-csv.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+
+import argparse
+import csv
+import os
+import sys
+from dataclasses import dataclass, asdict, fields
+from typing import List
+from gherkin.parser import Parser
+from gherkin.token_scanner import TokenScanner
+
+@dataclass
+class Rule:
+    """A class representing a rule extracted from a Gherkin feature file."""
+    identifier: str
+    description: str
+
+    @classmethod
+    def field_names(cls) -> List[str]:
+        return [f.name for f in fields(cls)]
+
+def extract_rules_from_feature(file_path):
+    """Parse a Gherkin feature file and extract the rules."""
+    with open(file_path, 'r', encoding='utf-8') as file:
+        content = file.read()
+
+    parser = Parser()
+    try:
+        feature_document = parser.parse(TokenScanner(content))
+        rules = []
+
+        if 'feature' in feature_document:
+            feature = feature_document['feature']
+
+            if 'children' in feature:
+                for child in feature['children']:
+                    if 'rule' in child:
+                        rule = child['rule']
+                        rule_id = rule.get('name', '').strip()
+                        description = rule.get('description', '').strip()
+                        rules.append(Rule(
+                            identifier=rule_id,
+                            description=description
+                        ))
+
+        return rules
+    except Exception as e:
+        print(f"Error parsing {file_path}: {e}", file=sys.stderr)
+        return []
+
+def main():
+    parser = argparse.ArgumentParser(description='Extract rules from Gherkin feature files and save to CSV')
+    parser.add_argument('feature_files', nargs='+', help='Paths to feature files')
+    parser.add_argument('--output', '-o', default='rules.csv', help='Output CSV file path')
+
+    args = parser.parse_args()
+    all_rules = []
+
+    for feature_path in args.feature_files:
+        if os.path.isfile(feature_path):
+            print(f"Processing {feature_path}")
+            rules = extract_rules_from_feature(feature_path)
+            all_rules.extend(rules)
+        else:
+            print(f"File not found: {feature_path}", file=sys.stderr)
+
+    with open(args.output, 'w', newline='', encoding='utf-8') as csvfile:
+        writer = csv.DictWriter(csvfile, fieldnames=Rule.field_names())
+        writer.writeheader()
+        writer.writerows([asdict(rule) for rule in all_rules])
+
+    print(f"Extracted {len(all_rules)} rules to {args.output}")
+
+if __name__ == '__main__':
+    main()
diff --git a/test/cpp/features/compilation.feature b/test/cpp/features/compilation.feature
index b2128ef8..99d367a9 100644
--- a/test/cpp/features/compilation.feature
+++ b/test/cpp/features/compilation.feature
@@ -1,10 +1,11 @@
-Feature: Compile source code into working software
+Feature: amp-devcontainer::compilation
 
   As a developer
   To generate working software
   Source code needs to be compiled successfully
 
-  Scenario: Compile valid source code into working software targeting the host architecture
+  Rule: amp-devcontainer::compilation.host-target
+    amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture.
 
     Compiling valid source code into working software, able to run on the host architecture,
     can be necessary in several scenarios; for example when:
@@ -13,7 +14,32 @@ Feature: Compile source code into working software
     - running tests on the host
     - building plug-ins, extensions, code generators, or other additional tools that need to run on the host
 
-    Given build configuration "gcc" is selected
-    And build preset "gcc" is selected
-    When the selected target is built
-    Then the output should contain "Build finished with exit code 0"
+    @flavor:cpp
+    Scenario: Compile valid source code into working software targeting the host architecture
+      Given build configuration "gcc" is selected
+      And build preset "gcc" is selected
+      When the selected target is built
+      Then the output should contain "Build finished with exit code 0"
+
+  Rule: amp-devcontainer::compilation.arm-target
+    amp-devcontainer *SHALL* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture.
+
+    Compiling valid source-code into working ELF executables, able to run on the ARM Cortex architecture,
+    is a primary function for amp-devcontainer. It enables building firmware for micro-controllers based
+    on the ARM Cortex architecture.
+
+  Rule: amp-devcontainer::compilation.windows-target
+    amp-devcontainer *SHALL* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system.
+
+    Compiling valid source-code into working executables, able to run on the Microsoft® Windows operating system, can be necessary in several scenarios e.g.
+
+    - Cross platform code is written and needs to be compiled and deployed
+    - Executables needs to be deployed outside of container context to a host running the Microsoft® Windows operating system
+
+  Rule: amp-devcontainer::compilation.cache
+    amp-devcontainer *SHOULD* be able to cache the results of a compilation to speed-up subsequent compilations.
+
+    Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like
+
+    - Reduce developer waiting time and context switches, [maintaining flow-state](https://azure.microsoft.com/en-us/blog/quantifying-the-impact-of-developer-experience/)
+    - Reduce CPU usage at the cost of more storage usage, potentially reducing energy consumption and cost for metered ci-systems

From ca61782fb054ad167d203841c1fdd15fd67c7ab6 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Wed, 24 Sep 2025 14:14:02 +0000
Subject: [PATCH 04/13] docs: generate requirements document

---
 .github/workflows/wc-document-generation.yml | 18 ++++++--
 docs/templates/requirements.template.md      | 45 ++++++++++++++++++++
 test/cpp/features/compilation.feature        | 30 ++++++-------
 3 files changed, 74 insertions(+), 19 deletions(-)
 create mode 100644 docs/templates/requirements.template.md

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index fb57e51a..b62f53d3 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -8,7 +8,7 @@ permissions:
   contents: read
 
 jobs:
-  generate-documentation:
+  generate-requirements:
     runs-on: ubuntu-latest
     steps:
       - uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
@@ -18,10 +18,20 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
-      - run: |
+      - name: Install dependencies
+        run: |
           set -Eeuo pipefail
-          python -m pip install gherkin-official https://sbdl.dev/sbdl-package.tar.gz
-      - run: |
+          sudo apt-get install --update --no-install-recommends -y pandoc plantuml texlive texlive-fonts-recommended
+          python -m pip install gherkin-official pytm sbdl
+      - name: Generate requirements document
+        run: |
           set -Eeuo pipefail
           python docs/support/gherkin-to-csv.py test/cpp/features/*.feature
           python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv
+          sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl | pandoc -f gfm -o requirements.pdf
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always()
+        with:
+          name: documents
+          path: requirements.pdf
+          retention-days: 2
diff --git a/docs/templates/requirements.template.md b/docs/templates/requirements.template.md
new file mode 100644
index 00000000..589a38b0
--- /dev/null
+++ b/docs/templates/requirements.template.md
@@ -0,0 +1,45 @@
+# amp-devcontainer requirement specification
+
+## Introduction
+
+### Purpose
+
+This document describes the software system requirements for amp-devcontainer.
+
+### Definitions of key words
+
+The key words *MUST*, *MUST NOT*, *REQUIRED*, *SHALL*, *SHALL NOT*, *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *MAY*, and *OPTIONAL* in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
+
+### Abstract
+
+amp-devcontainer is a set of [devcontainers](https://containers.dev/) tailored towards modern, embedded, software development.
+
+The containers may be used both for local development and continuous integration (ci).
+
+### Terminology and Abbreviations
+
+| Terminology and Abbreviations | Description/Definition                                                                                                                 |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| ARM                           | A family of RISC architectures for computer processors and micro controllers, formerly an acronym for Advanced RISC Machines and originally Acorn RISC Machine |
+| Continuous Integration (ci)   | The practice of continuously merging developers work to a shared code-base; ideally including automation for build, test and deployment |
+| ELF                           | Executable and Linkable Format, formerly named Extensible Linking Format |
+| RISC                          | Reduced Instruction Set Computer |
+
+## Requirements
+
+{%- macro reencode(text) -%}
+{{ text.encode('utf-8').decode('unicode_escape') }}
+{%- endmacro -%}
+
+{%- macro sbdl_id_to_header(text) -%}
+{{ text.replace('_', ' ') }}
+{%- endmacro -%}
+
+{% for req_id, requirement in sbdl.items() %}
+{% if requirement.type == 'requirement' %}
+### {{ reencode(sbdl_id_to_header(req_id)) }}
+
+{{ reencode(requirement.description) }}
+
+{% endif %}
+{% endfor %}
diff --git a/test/cpp/features/compilation.feature b/test/cpp/features/compilation.feature
index 99d367a9..d2bce27e 100644
--- a/test/cpp/features/compilation.feature
+++ b/test/cpp/features/compilation.feature
@@ -1,34 +1,34 @@
-Feature: amp-devcontainer::compilation
+Feature: Compilation
 
-  As a developer
-  To generate working software
-  Source code needs to be compiled successfully
+  As a software developer
+  To generate a working product
+  Source code needs to be compiled into working software
 
-  Rule: amp-devcontainer::compilation.host-target
-    amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture.
+  Rule: Compile for container host architecture and operating system
+    amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the container host architecture and operating system.
 
-    Compiling valid source code into working software, able to run on the host architecture,
+    Compiling valid source code into working software, able to run on the container host architecture and operating system,
     can be necessary in several scenarios; for example when:
 
-    - the host is the deployment target
-    - running tests on the host
-    - building plug-ins, extensions, code generators, or other additional tools that need to run on the host
+    - the container host is the deployment target
+    - running tests on the container host
+    - building plug-ins, extensions, code generators, or other additional tools that need to run on the container host
 
     @flavor:cpp
-    Scenario: Compile valid source code into working software targeting the host architecture
+    Scenario: Compile valid source code into working software targeting the container host architecture
       Given build configuration "gcc" is selected
       And build preset "gcc" is selected
       When the selected target is built
       Then the output should contain "Build finished with exit code 0"
 
-  Rule: amp-devcontainer::compilation.arm-target
+  Rule: Compile for ARM Cortex target architecture
     amp-devcontainer *SHALL* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture.
 
     Compiling valid source-code into working ELF executables, able to run on the ARM Cortex architecture,
     is a primary function for amp-devcontainer. It enables building firmware for micro-controllers based
     on the ARM Cortex architecture.
 
-  Rule: amp-devcontainer::compilation.windows-target
+  Rule: Compile for Microsoft® Windows operating system
     amp-devcontainer *SHALL* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system.
 
     Compiling valid source-code into working executables, able to run on the Microsoft® Windows operating system, can be necessary in several scenarios e.g.
@@ -36,10 +36,10 @@ Feature: amp-devcontainer::compilation
     - Cross platform code is written and needs to be compiled and deployed
     - Executables needs to be deployed outside of container context to a host running the Microsoft® Windows operating system
 
-  Rule: amp-devcontainer::compilation.cache
+  Rule: Compilation cache
     amp-devcontainer *SHOULD* be able to cache the results of a compilation to speed-up subsequent compilations.
 
-    Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like
+    Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like:
 
     - Reduce developer waiting time and context switches, [maintaining flow-state](https://azure.microsoft.com/en-us/blog/quantifying-the-impact-of-developer-experience/)
     - Reduce CPU usage at the cost of more storage usage, potentially reducing energy consumption and cost for metered ci-systems

From e3cc6600c0165139633d002a98df27cbf020ad99 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Wed, 24 Sep 2025 14:15:28 +0000
Subject: [PATCH 05/13] fix: don't use sudo in workflows

---
 .github/workflows/wc-document-generation.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index b62f53d3..f14707f2 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -21,7 +21,7 @@ jobs:
       - name: Install dependencies
         run: |
           set -Eeuo pipefail
-          sudo apt-get install --update --no-install-recommends -y pandoc plantuml texlive texlive-fonts-recommended
+          apt-get install --update --no-install-recommends -y pandoc plantuml texlive texlive-fonts-recommended
           python -m pip install gherkin-official pytm sbdl
       - name: Generate requirements document
         run: |

From 176a0f06d232b4c44767cee6790d13b38ee48c71 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Wed, 24 Sep 2025 14:18:43 +0000
Subject: [PATCH 06/13] fix: allow sudo in workflow that needs it

---
 .github/workflows/wc-document-generation.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index f14707f2..e93f80d7 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -13,7 +13,6 @@ jobs:
     steps:
       - uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
         with:
-          disable-sudo-and-containers: true
           egress-policy: audit
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
@@ -21,7 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           set -Eeuo pipefail
-          apt-get install --update --no-install-recommends -y pandoc plantuml texlive texlive-fonts-recommended
+          sudo apt-get install --update --no-install-recommends -y pandoc plantuml texlive texlive-fonts-recommended
           python -m pip install gherkin-official pytm sbdl
       - name: Generate requirements document
         run: |

From ada3cacde5763aa892a4b4ae776492c7dbe41f29 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Wed, 24 Sep 2025 14:28:43 +0000
Subject: [PATCH 07/13] ci: install missing package

---
 .github/workflows/wc-document-generation.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index e93f80d7..a6717712 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -8,7 +8,7 @@ permissions:
   contents: read
 
 jobs:
-  generate-requirements:
+  generate-documents:
     runs-on: ubuntu-latest
     steps:
       - uses: step-security/harden-runner@002fdce3c6a235733a90a27c80493a3241e56863 # v2.12.1
@@ -20,7 +20,7 @@ jobs:
       - name: Install dependencies
         run: |
           set -Eeuo pipefail
-          sudo apt-get install --update --no-install-recommends -y pandoc plantuml texlive texlive-fonts-recommended
+          sudo apt-get install --update --no-install-recommends -y lmodern pandoc plantuml texlive texlive-fonts-recommended
           python -m pip install gherkin-official pytm sbdl
       - name: Generate requirements document
         run: |

From c8df85bff350c250555ca4a7a50e577f9aac1b85 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Thu, 25 Sep 2025 07:09:36 +0200
Subject: [PATCH 08/13] Apply suggestions from code review

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Signed-off-by: Ron <45816308+rjaegers@users.noreply.github.com>
---
 docs/templates/requirements.template.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/templates/requirements.template.md b/docs/templates/requirements.template.md
index 589a38b0..3b941f2a 100644
--- a/docs/templates/requirements.template.md
+++ b/docs/templates/requirements.template.md
@@ -18,12 +18,12 @@ The containers may be used both for local development and continuous integration
 
 ### Terminology and Abbreviations
 
-| Terminology and Abbreviations | Description/Definition                                                                                                                 |
-|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| Terminology and Abbreviations | Description/Definition                                                                                                                                         |
+|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | ARM                           | A family of RISC architectures for computer processors and micro controllers, formerly an acronym for Advanced RISC Machines and originally Acorn RISC Machine |
-| Continuous Integration (ci)   | The practice of continuously merging developers work to a shared code-base; ideally including automation for build, test and deployment |
-| ELF                           | Executable and Linkable Format, formerly named Extensible Linking Format |
-| RISC                          | Reduced Instruction Set Computer |
+| Continuous Integration (ci)   | The practice of continuously merging developers work to a shared code-base; ideally including automation for build, test and deployment                        |
+| ELF                           | Executable and Linkable Format, formerly named Extensible Linking Format                                                                                       |
+| RISC                          | Reduced Instruction Set Computer                                                                                                                               |
 
 ## Requirements
 

From ac7263d7894e1f8f41e5d4e3753b0d9ae2d6535d Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Thu, 25 Sep 2025 10:43:19 +0000
Subject: [PATCH 09/13] docs: generate nicer PDF

---
 .github/workflows/wc-document-generation.yml | 9 +++++----
 docs/support/gherkin-to-csv.py               | 8 ++++----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index a6717712..878e5f83 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -20,14 +20,15 @@ jobs:
       - name: Install dependencies
         run: |
           set -Eeuo pipefail
-          sudo apt-get install --update --no-install-recommends -y lmodern pandoc plantuml texlive texlive-fonts-recommended
-          python -m pip install gherkin-official pytm sbdl
+          sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
+          python -m pip install gherkin-official sbdl
       - name: Generate requirements document
         run: |
           set -Eeuo pipefail
           python docs/support/gherkin-to-csv.py test/cpp/features/*.feature
-          python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv
-          sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl | pandoc -f gfm -o requirements.pdf
+          python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv -o - | sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl > requirements.md
+      - uses: docker://pandoc/latex:3.7@sha256:ea5a6702bd47aea68dc1da18ff7e9891a76097d10ae88ea03d343113114dcbbe
+        args: --output requirements.pdf requirements.md
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         if: always()
         with:
diff --git a/docs/support/gherkin-to-csv.py b/docs/support/gherkin-to-csv.py
index d2e71da7..5144c632 100755
--- a/docs/support/gherkin-to-csv.py
+++ b/docs/support/gherkin-to-csv.py
@@ -21,11 +21,11 @@ def field_names(cls) -> List[str]:
 
 def extract_rules_from_feature(file_path):
     """Parse a Gherkin feature file and extract the rules."""
-    with open(file_path, 'r', encoding='utf-8') as file:
-        content = file.read()
-
-    parser = Parser()
     try:
+        with open(file_path, 'r', encoding='utf-8') as file:
+            content = file.read()
+
+        parser = Parser()
         feature_document = parser.parse(TokenScanner(content))
         rules = []
 

From 9c37fe18450ce65b7fdc5dffe198c428cdaf18cb Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Thu, 25 Sep 2025 10:49:05 +0000
Subject: [PATCH 10/13] chore: correct workflow syntax

---
 .github/workflows/wc-document-generation.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index 878e5f83..28c04808 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -28,7 +28,8 @@ jobs:
           python docs/support/gherkin-to-csv.py test/cpp/features/*.feature
           python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv -o - | sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl > requirements.md
       - uses: docker://pandoc/latex:3.7@sha256:ea5a6702bd47aea68dc1da18ff7e9891a76097d10ae88ea03d343113114dcbbe
-        args: --output requirements.pdf requirements.md
+        with:
+          args: --output requirements.pdf requirements.md
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         if: always()
         with:

From becc9918a5328342a78b5c5c656c4966c8e89e1b Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Thu, 25 Sep 2025 11:07:24 +0000
Subject: [PATCH 11/13] chore: minor refactor to workflow

---
 .github/workflows/wc-document-generation.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index 28c04808..e56f0b95 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -26,12 +26,12 @@ jobs:
         run: |
           set -Eeuo pipefail
           python docs/support/gherkin-to-csv.py test/cpp/features/*.feature
-          python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv -o - | sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl > requirements.md
+          python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv
+          sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl > requirements.md
       - uses: docker://pandoc/latex:3.7@sha256:ea5a6702bd47aea68dc1da18ff7e9891a76097d10ae88ea03d343113114dcbbe
         with:
           args: --output requirements.pdf requirements.md
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        if: always()
         with:
           name: documents
           path: requirements.pdf

From a11b9678f687b6a2305ece72cc87b22cc49e246e Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Thu, 25 Sep 2025 11:36:31 +0000
Subject: [PATCH 12/13] chore: pin pip dependencies

---
 .github/workflows/wc-document-generation.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index e56f0b95..d0dab448 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -21,7 +21,7 @@ jobs:
         run: |
           set -Eeuo pipefail
           sudo apt-get update && sudo apt-get install --no-install-recommends -y plantuml
-          python -m pip install gherkin-official sbdl
+          python -m pip install gherkin-official==35.1.0 sbdl==1.16.4
       - name: Generate requirements document
         run: |
           set -Eeuo pipefail

From 8caaba23f953f9b952983a0da1b8fe75d574aaf9 Mon Sep 17 00:00:00 2001
From: Ron <45816308+rjaegers@users.noreply.github.com>
Date: Thu, 25 Sep 2025 12:11:52 +0000
Subject: [PATCH 13/13] docs: make the pdf more appealing

---
 .github/workflows/wc-document-generation.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/wc-document-generation.yml b/.github/workflows/wc-document-generation.yml
index d0dab448..4241b822 100644
--- a/.github/workflows/wc-document-generation.yml
+++ b/.github/workflows/wc-document-generation.yml
@@ -28,9 +28,9 @@ jobs:
           python docs/support/gherkin-to-csv.py test/cpp/features/*.feature
           python -m csv-to-sbdl --identifier 0 --description 1 --skipheader rules.csv
           sbdl -m template-fill --template docs/templates/requirements.template.md output.sbdl > requirements.md
-      - uses: docker://pandoc/latex:3.7@sha256:ea5a6702bd47aea68dc1da18ff7e9891a76097d10ae88ea03d343113114dcbbe
+      - uses: docker://pandoc/extra:3.7.0@sha256:a703d335fa237f8fc3303329d87e2555dca5187930da38bfa9010fa4e690933a
         with:
-          args: --output requirements.pdf requirements.md
+          args: --template eisvogel --output requirements.pdf requirements.md
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: documents