doc: twister: add documentation of integration_toolchains

Document the new option and how to use integration_toolchains.

Signed-off-by: Anas Nashif <[email protected]>

Author: nashif

doc/develop/test/twister.rst

@@ -478,6 +478,40 @@ integration_platforms: <YML list of platforms/boards>
     platform_allow if the goal is to limit scope due to timing or
     resource constraints.
 
+integration_toolchains: <YML list of toolchain variants>
+    This option expands the scope to all the listed toolchains variants and
+    adds another vector of testing where desired. By default, test
+    configurations are generated based on the toolchain configured in the environment:
+
+    test scenario -> platforms1 -> toolchain1
+    test scenario -> platforms2 -> toolchain1
+
+
+    When a platform supports multiple toolchains that are available during the
+    twister run, it is possible to expand the test configurations to include
+    additional tests for each toolchain. For example, if a platform supports
+    toolchains ``toolchain1`` and ``toolchain2``, and the test scenario
+    includes:
+
+    .. code-block:: yaml
+
+      integration_toolchains:
+        - toolchain1
+        - toolchain2
+
+    the following configurations are generated:
+
+    test scenario -> platforms1 -> toolchain1
+    test scenario -> platforms1 -> toolchain2
+    test scenario -> platforms2 -> toolchain1
+    test scenario -> platforms2 -> toolchain2
+
+
+    .. note::
+
+      This functionality is evaluated always and is not limited to the
+      ``--integration`` option.
+
 platform_exclude: <list of platforms>
     Set of platforms that this test scenario should not run on.