docs: formatting changes

rjaegers · rjaegers · commit aa364166a2da · 2026-03-07T15:51:30.000Z
diff --git a/docs/templates/software-requirements-specification.md.j2 b/docs/templates/software-requirements-specification.md.j2
@@ -53,7 +53,7 @@ The containers may be used both for local development and continuous integration
 {%- for aspect_id, aspect in sbdl.items() %}
 {%- if aspect.type == 'aspect' %}
 
-## {{ reencode(strip_gherkin_prefix(aspect_id)) | title }}
+## {{ reencode(strip_gherkin_prefix(aspect['custom:title'])) }}
 
 {{ reencode(aspect.description) }}
 
diff --git a/test/cpp/features/compatibility.feature b/test/cpp/features/compatibility.feature
@@ -29,16 +29,15 @@ Feature: Compatibility
       req-compat-0002 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64)
-         *and* AArch64 (ARM64) host architectures."
+        "amp-devcontainer *SHALL* be compatible with both the x86-64 (AMD64) *and* AArch64 (ARM64)
+        host architectures."
         remark is
-        "Supporting both x86-64 and AArch64 has several advantages:
+        "Supporting both x86-64 and AArch64 has several advantages:\n\n
 
-         - Increasing usability on a wide range of host machines,
-           from PC hardware using the x86-64 architecture to
-           Apple Silicon using the AArch64 architecture
-         - Unlocking the power efficiency of the AArch64 architecture,
-           potentially reducing energy consumption and cost for metered ci-systems"
+         - Increasing usability on a wide range of host machines, from PC hardware using the x86-64
+           architecture to Apple Silicon using the AArch64 architecture\n
+         - Unlocking the power efficiency of the AArch64 architecture, potentially reducing energy
+           consumption and cost for metered ci-systems"
       }
     # @sbdl-end
 
@@ -50,11 +49,11 @@ Feature: Compatibility
         "amp-devcontainer *SHOULD* be compatible with [VS Code](https://code.visualstudio.com/)
          *and* [GitHub Codespaces](https://github.com/features/codespaces)."
         remark is
-        "It should be possible to use amp-devcontainer and all of its features in both VS Code
-         and GitHub Codespaces with minimal effort. Where minimal effort means: with the least
-         amount of additional set-up, user intervention or configuration for all functionality
-         that is provided by amp-devcontainer. Features and functions should work \"out-of-the-box\"
-         without being overly opinionated."
+        "It should be possible to use amp-devcontainer and all of its features in both VS Code and
+         GitHub Codespaces with minimal effort. Where minimal effort means: with the least amount of
+         additional set-up, user intervention or configuration for all functionality that is
+         provided by amp-devcontainer. Features and functions should work \"out-of-the-box\" without
+         being overly opinionated."
       }
     # @sbdl-end
 
@@ -66,11 +65,10 @@ Feature: Compatibility
         "amp-devcontainer *SHOULD* support seamless integration with
          [GitHub Actions](https://github.com/features/actions) without additional configuration."
         remark is
-        "Seamless integration with GitHub Actions allows users to easily incorporate
-         amp-devcontainer into their ci/cd workflows. This integration helps automate
-         the build, test, and deployment processes, improving efficiency and reducing
-         manual errors. By minimizing the need for additional configuration, users can
-         quickly set up and start using amp-devcontainer in their GitHub Actions workflows,
-         enhancing their overall development experience."
+        "Seamless integration with GitHub Actions allows users to easily incorporate amp-devcontainer
+         into their ci/cd workflows. This integration helps automate the build, test, and deployment
+         processes, improving efficiency and reducing manual errors. By minimizing the need for
+         additional configuration, users can quickly set up and start using amp-devcontainer in their
+         GitHub Actions workflows, enhancing their overall development experience."
       }
     # @sbdl-end
diff --git a/test/cpp/features/compilation.feature b/test/cpp/features/compilation.feature
@@ -16,10 +16,16 @@ Feature: Compilation
       req-comp-0001 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHALL* be able to compile valid source code into a working executable targeting the 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."
         remark is
-        "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:\n\n- the container host is the deployment target\n- running tests on the container host\n- building plug-ins, extensions, code generators, or other additional tools that need to run on the container host"
+        "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:\n\n
+
+         - the container host is the deployment target\n
+         - running tests on the container host\n
+         - building plug-ins, extensions, code generators, or other additional tools that need to
+           run on the container host"
       }
     # @sbdl-end
 
@@ -35,11 +41,12 @@ Feature: Compilation
       req-comp-0002 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHOULD* be able to compile valid source-code into a working ELF executable targeting the ARM Cortex architecture."
+        "amp-devcontainer *SHOULD* be able to compile valid source-code into a working ELF
+         executable targeting the ARM Cortex architecture."
         remark is
-        "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."
+        "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."
       }
     # @sbdl-end
 
@@ -48,9 +55,15 @@ Feature: Compilation
       req-comp-0003 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHOULD* be able to compile valid source-code into a working executable targeting the Microsoft® Windows operating system."
+        "amp-devcontainer *SHOULD* be able to compile valid source-code into a working executable
+        targeting the Microsoft® Windows operating system."
         remark is
-        "Compiling valid source-code into working executables, able to run on the Microsoft® Windows operating system, can be necessary in several scenarios e.g.\n\n- Cross platform code is written and needs to be compiled and deployed\n- Executables needs to be deployed outside of container context to a host running 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.\n\n
+
+         - Cross platform code is written and needs to be compiled and deployed\n
+         - Executables needs to be deployed outside of container context to a host running the
+           Microsoft® Windows operating system"
       }
     # @sbdl-end
 
@@ -59,8 +72,15 @@ Feature: Compilation
       req-comp-0004 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *MAY* be able to cache the results of a compilation to speed-up subsequent compilations."
+        "amp-devcontainer *MAY* be able to cache the results of a compilation to speed-up subsequent
+         compilations."
         remark is
-        "Maintaining a compilation cache can be useful in both local and ci development scenarios. A compilation cache can provide benefits like:\n\n- Reduce developer waiting time and context switches, [maintaining flow-state](https://azure.microsoft.com/en-us/blog/quantifying-the-impact-of-developer-experience/)\n- Reduce CPU usage at the cost of more storage usage, potentially reducing energy consumption and cost for metered ci-systems"
+        "Maintaining a compilation cache can be useful in both local and ci development scenarios.
+         A compilation cache can provide benefits like:\n\n
+
+         - Reduce developer waiting time and context switches,
+           [maintaining flow-state](https://azure.microsoft.com/en-us/blog/quantifying-the-impact-of-developer-experience/)\n
+         - Reduce CPU usage at the cost of more storage usage, potentially reducing energy
+           consumption and cost for metered ci-systems"
       }
     # @sbdl-end
diff --git a/test/cpp/features/debugging.feature b/test/cpp/features/debugging.feature
@@ -16,12 +16,16 @@ Feature: Debugging
       req-debug-0001 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHALL* provide debugging support for the primary programming language(s) used within the container."
+        "amp-devcontainer *SHALL* provide debugging support for the primary programming language(s)
+         used within the container."
         remark is
-        "Providing debugging support within the development environment enhances the developer experience and productivity.
-         It allows developers to efficiently identify and resolve issues in their code by setting breakpoints, inspecting variables, and stepping through code execution.
-         This capability is essential for diagnosing complex problems, understanding code flow, and ensuring the correctness of software.
-         By having integrated debugging tools, developers can streamline their workflow and reduce the time spent on troubleshooting and fixing bugs."
+        "Providing debugging support within the development environment enhances the developer
+         experience and productivity. It allows developers to efficiently identify and resolve
+         issues in their code by setting breakpoints, inspecting variables, and stepping through
+         code execution. This capability is essential for diagnosing complex problems, understanding
+         code flow, and ensuring the correctness of software. By having integrated debugging tools,
+         developers can streamline their workflow and reduce the time spent on troubleshooting and
+         fixing bugs."
       }
     # @sbdl-end
 
@@ -30,11 +34,15 @@ Feature: Debugging
       req-debug-0002 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *MAY* provide tools to upload compiled firmware to a connected micro-controller."
+        "amp-devcontainer *MAY* provide tools to upload compiled firmware to a connected
+         micro-controller."
         remark is
-        "Providing tools to upload compiled firmware to a connected micro-controller enhances the development workflow for embedded systems.
-         It allows developers to quickly and easily transfer their compiled code to the target hardware for testing and debugging.
-         This capability is essential for validating the functionality of the firmware on the actual device, ensuring that it behaves as expected in real-world scenarios.
-         By having integrated tools for firmware upload, developers can streamline their workflow, reduce manual steps, and improve overall productivity when working with micro-controllers."
+        "Providing tools to upload compiled firmware to a connected micro-controller enhances the
+         development workflow for embedded systems. It allows developers to quickly and easily
+         transfer their compiled code to the target hardware for testing and debugging. This
+         capability is essential for validating the functionality of the firmware on the actual
+         device, ensuring that it behaves as expected in real-world scenarios. By having integrated
+         tools for firmware upload, developers can streamline their workflow, reduce manual steps,
+         and improve overall productivity when working with micro-controllers."
       }
     # @sbdl-end
diff --git a/test/cpp/features/maintainability.feature b/test/cpp/features/maintainability.feature
@@ -18,9 +18,11 @@ Feature: Maintainability
         description is
         "amp-devcontainer *SHOULD* contain up-to-date tools and dependencies."
         remark is
-        "Keeping tools and dependencies up-to-date helps ensure that the development environment remains secure, stable, and compatible with the latest technologies.
-         It also helps prevent issues related to deprecated or unsupported software versions, reducing maintenance overhead and improving overall developer productivity.
-         Regular updates can also introduce new features and improvements that enhance the development experience."
+        "Keeping tools and dependencies up-to-date helps ensure that the development environment
+        remains secure, stable, and compatible with the latest technologies. It also helps prevent
+        issues related to deprecated or unsupported software versions, reducing maintenance overhead
+        and improving overall developer productivity. Regular updates can also introduce new
+        features and improvements that enhance the development experience."
       }
     # @sbdl-end
 
@@ -29,11 +31,15 @@ Feature: Maintainability
       req-maint-0002 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHOULD* provide support for automatic updates when consumed as a dependency."
+        "amp-devcontainer *SHOULD* provide support for automatic updates when consumed as a
+        dependency."
         remark is
-        "Providing support for automatic updates when amp-devcontainer is consumed as a dependency helps ensure that users always have access to the latest features, bug fixes, and security patches.
-         This reduces the maintenance burden on users, as they do not need to manually track and apply updates.
-         Automatic updates can also help ensure compatibility with other dependencies and tools, improving the overall stability and reliability of the development environment."
+        "Providing support for automatic updates when amp-devcontainer is consumed as a dependency
+        helps ensure that users always have access to the latest features, bug fixes, and security
+        patches. This reduces the maintenance burden on users, as they do not need to manually
+        track and apply updates. Automatic updates can also help ensure compatibility with other
+        dependencies and tools, improving the overall stability and reliability of the development
+        environment."
       }
     # @sbdl-end
 
@@ -42,10 +48,14 @@ Feature: Maintainability
       req-maint-0003 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHOULD* provide re-usable building blocks to enable building, publishing and testing derived containers."
+        "amp-devcontainer *SHOULD* provide re-usable building blocks to enable building, publishing
+         and testing derived containers."
         remark is
-        "Providing re-usable building blocks for building, publishing and testing derived containers reduces duplication, and ensures consistent application of practices.
-         Derived containers (i.e. containers using amp-devcontainer as a base for further extension) should be able to build, push and test in the same way that amp-devcontainer does, without the need to duplicate the build system."
+        "Providing re-usable building blocks for building, publishing and testing derived containers
+         reduces duplication, and ensures consistent application of practices. Derived containers
+         (i.e. containers using amp-devcontainer as a base for further extension) should be able to
+         build, push and test in the same way that amp-devcontainer does, without the need to
+         duplicate the build system."
       }
     # @sbdl-end
 
@@ -56,9 +66,12 @@ Feature: Maintainability
         description is
         "amp-devcontainer *SHOULD* document its architectural decisions."
         remark is
-        "Documenting architectural decisions helps provide context and rationale for the design choices made in the development environment.
-         This information can be valuable for future maintainers, as it helps them understand the reasoning behind certain implementations and can guide them in making informed decisions when modifying or extending the environment.
-         Clear documentation of architectural decisions can also facilitate collaboration among team members and improve overall maintainability."
+        "Documenting architectural decisions helps provide context and rationale for the design
+        choices made in the development environment. This information can be valuable for future
+        maintainers, as it helps them understand the reasoning behind certain implementations and
+        can guide them in making informed decisions when modifying or extending the environment.
+        Clear documentation of architectural decisions can also facilitate collaboration among team
+        members and improve overall maintainability."
       }
     # @sbdl-end
 
@@ -67,15 +80,13 @@ Feature: Maintainability
       req-maint-0005 is requirement {
         custom:title is "[@-LINE]"
         description is
-        "amp-devcontainer *SHOULD* aim to keep its container image size as small as possible without compromising functionality."
+        "amp-devcontainer *SHOULD* aim to keep its container image size as small as possible without
+         compromising functionality."
         remark is
-        "Keeping the container image size small helps improve performance, reduce resource consumption, and minimize the time required to download and deploy the development environment.
-         A smaller image size can also help reduce storage costs and improve scalability, particularly in cloud-based environments.
-         By optimizing the container image size, amp-devcontainer can provide a more efficient and user-friendly experience for developers."
+        "Keeping the container image size small helps improve performance, reduce resource
+        consumption, and minimize the time required to download and deploy the development
+        environment. A smaller image size can also help reduce storage costs and improve scalability,
+        particularly in cloud-based environments. By optimizing the container image size,
+        amp-devcontainer can provide a more efficient and user-friendly experience for developers."
       }
     # @sbdl-end
-
-    <acceptance-criteria>
-    - The container image size is monitored.
-    - The compressed image size is kept below 1 GiB.
-    </acceptance-criteria>
diff --git a/test/cpp/features/security.feature b/test/cpp/features/security.feature
diff --git a/test/cpp/features/static-dynamic-analysis.feature b/test/cpp/features/static-dynamic-analysis.feature
