From cae12e6d6a7d50cb7a333fa6fcb37dd91d8749c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= <benjamin@zephyrproject.org>
Date: Tue, 8 Jul 2025 17:56:42 +0200
Subject: [PATCH] doc: twister: inline `twister --help` output into the docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to make it easier for folks to discover available twister
options when using/searching the documentation, or when making external
search in their favorite search engine, inline the output of
`twister --help` into the docs so as to have an always up-to-date
and searchable snapshot of it.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
---
 doc/conf.py                  | 1 +
 doc/develop/test/twister.rst | 5 ++---
 doc/requirements.in          | 1 +
 doc/requirements.txt         | 6 ++++++
 4 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 60e91d0dd0b..76004dfe30c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -76,6 +76,7 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.graphviz",
     "sphinxcontrib.jquery",
+    "sphinxcontrib.programoutput",
     "zephyr.application",
     "zephyr.html_redirects",
     "zephyr.kconfig",
diff --git a/doc/develop/test/twister.rst b/doc/develop/test/twister.rst
index 64aa90f79b9..701f40fb399 100644
--- a/doc/develop/test/twister.rst
+++ b/doc/develop/test/twister.rst
@@ -83,9 +83,8 @@ The list of command line options supported by twister can be viewed using:
 
    .. group-tab:: Linux
 
-      .. code-block:: bash
-
-         $ ./scripts/twister --help
+      .. command-output:: $ZEPHYR_BASE/scripts/twister --help
+         :shell:
 
    .. group-tab:: Windows
 
diff --git a/doc/requirements.in b/doc/requirements.in
index 36bb61a00c8..4e5611bd593 100644
--- a/doc/requirements.in
+++ b/doc/requirements.in
@@ -10,6 +10,7 @@ sphinx-copybutton
 sphinx-togglebutton
 sphinx-sitemap
 sphinx-autobuild
+sphinxcontrib.programoutput
 
 # YAML validation. Used by zephyr_module.
 PyYAML>=6.0
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 255ff1321a5..25ec15e4ab3 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -508,6 +508,7 @@ sphinx==8.1.3 ; python_full_version < '3.11' \
     #   sphinx-tabs
     #   sphinx-togglebutton
     #   sphinxcontrib-jquery
+    #   sphinxcontrib-programoutput
     #   sphinxcontrib-svg2pdfconverter
 sphinx==8.2.3 ; python_full_version >= '3.11' \
     --hash=sha256:398ad29dee7f63a75888314e9424d40f52ce5a6a87ae88e7071e80af296ec348 \
@@ -522,6 +523,7 @@ sphinx==8.2.3 ; python_full_version >= '3.11' \
     #   sphinx-tabs
     #   sphinx-togglebutton
     #   sphinxcontrib-jquery
+    #   sphinxcontrib-programoutput
     #   sphinxcontrib-svg2pdfconverter
 sphinx-autobuild==2024.10.3 \
     --hash=sha256:158e16c36f9d633e613c9aaf81c19b0fc458ca78b112533b20dafcda430d60fa \
@@ -575,6 +577,10 @@ sphinxcontrib-jsmath==1.0.1 \
     --hash=sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178 \
     --hash=sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8
     # via sphinx
+sphinxcontrib-programoutput==0.18 \
+    --hash=sha256:09e68b6411d937a80b6085f4fdeaa42e0dc5555480385938465f410589d2eed8 \
+    --hash=sha256:8a651bc85de69a808a064ff0e48d06c12b9347da4fe5fdb1e94914b01e1b0c36
+    # via -r requirements.in
 sphinxcontrib-qthelp==2.0.0 \
     --hash=sha256:4fe7d0ac8fc171045be623aba3e2a8f613f8682731f9153bb2e40ece16b9bbab \
     --hash=sha256:b18a828cdba941ccd6ee8445dbe72ffa3ef8cbe7505d8cd1fa0d42d3f2d5f3eb