[PATCH] doc: elaborate on per test suite configuration dts docs

[PATCH] doc: elaborate on per test suite configuration dts docs

[Nicholas Pratte]

Introduce some additional documentation explaing the per test suite
configuration component of DTS as the current dts documentation does
not provide a quick access reference guide or explanation.

Signed-off-by: Nicholas Pratte <npratte@iol.unh.edu>
---
 doc/guides/tools/dts.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/guides/tools/dts.rst b/doc/guides/tools/dts.rst
index fcc6d22036..951b5462e2 100644
--- a/doc/guides/tools/dts.rst
+++ b/doc/guides/tools/dts.rst
@@ -405,6 +405,13 @@ There are four types of methods that comprise a test suite:
    If there's any functionality or logic missing from the framework,
    it should be implemented so that the test suites can use one of these two ways.
 
+   Test suites may also be configured individually using a provided configuration file,
+   provided at the command line, for custom configuration. The configuration file is a simple
+   mapping of test suite names to their corresponding configurations.
+
+   Any test suite can be designed to require custom configuration attributes or optional ones.
+   Any optional attributes should supply a default value for the test suite to use.
+
 #. **Test case verification**
 
    Test case verification should be done with the ``verify`` method, which records the result.
@@ -507,3 +514,18 @@ And they both have two network ports which are physically connected to each othe
 .. literalinclude:: ../../../dts/nodes.example.yaml
    :language: yaml
    :start-at: # Define
+
+Additionally, an example configuration file is provided to demonstrate custom test suite configuration:
+
+.. note::
+   You do not neeed to supply configurations for all test suites, and not all test suites will support
+   or need additional configuration.
+
+.. _tests_config_example:
+
+``dts/tests_config.example.yaml``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: ../../../dts/tests_config.example.yaml
+   :language: yaml
+   :start-at: # Define
\ No newline at end of file
-- 
2.47.1

Re: [PATCH] doc: elaborate on per test suite configuration dts docs

[Dean Marx]

On Fri, May 16, 2025 at 4:26 PM Nicholas Pratte <npratte@iol.unh.edu> wrote:
>
> Introduce some additional documentation explaing the per test suite
> configuration component of DTS as the current dts documentation does
> not provide a quick access reference guide or explanation.
>
> Signed-off-by: Nicholas Pratte <npratte@iol.unh.edu>

explaining is misspelled in the commit message

<snip>
> +   Test suites may also be configured individually using a provided configuration file,
> +   provided at the command line, for custom configuration. The configuration file is a simple
> +   mapping of test suite names to their corresponding configurations.

This part is a little odd, the words configured/configuration and
provided are used a lot. Maybe something like this would be better:
"Test suites may also be configured individually using a file provided
at the command line. This file is a simple mapping of test suite names
to their corresponding configurations."

Reviewed-by: Dean Marx <dmarx@iol.unh.edu>

Re: [PATCH] doc: elaborate on per test suite configuration dts docs

[Luca Vizzarro]

Agree with Dean's changes. Also the start marker is broken, but can 
easily be added.

Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>