[PATCH v1] dts: add test case docstring checks to format script

[Dean Marx]

Add a python script that checks all test cases
to ensure each docstring contains a steps and
verify section in accordance with coding guidelines.
Add a section within the check-format script which
calls the docstring script after linting with ruff.

Bugzilla ID: 1623

Signed-off-by: Dean Marx <dmarx at iol.unh.edu>
---
 devtools/check-docstrings.py | 52 ++++++++++++++++++++++++++++++++++++
 devtools/dts-check-format.sh |  7 +++++
 2 files changed, 59 insertions(+)
 create mode 100755 devtools/check-docstrings.py

diff --git a/devtools/check-docstrings.py b/devtools/check-docstrings.py
new file mode 100755
index 0000000000..0baee6e383
--- /dev/null
+++ b/devtools/check-docstrings.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2025 University of New Hampshire
+
+import sys
+from ast import FunctionDef, Name, walk, get_docstring, parse
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent  # dpdk/
+TESTS_DIR = BASE_DIR.parent / "dts" / "tests"  # dts/tests/
+
+
+def has_test_decorator(node: FunctionDef) -> bool:
+    """Return True if function has @func_test or @perf_test decorator."""
+    for decorator in node.decorator_list:
+        if isinstance(decorator, Name) and decorator.id in {"func_test", "perf_test"}:
+            return True
+    return False
+
+
+def check_file(path: Path) -> bool:
+    """Return True if file has steps and verify sections in each test case docstring."""
+    source = path.read_text(encoding="utf-8")
+    tree = parse(source, filename=str(path))
+    ok = True
+
+    for node in walk(tree):
+        if isinstance(node, FunctionDef):
+            if has_test_decorator(node):
+                doc = get_docstring(node)
+                if not doc:
+                    print(f"{path}:{node.lineno} missing docstring for test case")
+                    ok = False
+                else:
+                    if "Steps:" not in doc:
+                        print(f"{path}:{node.lineno} missing 'Steps:' section")
+                        ok = False
+                    if "Verify:" not in doc:
+                        print(f"{path}:{node.lineno} missing 'Verify:' section")
+                        ok = False
+    return ok
+
+
+def main():
+    all_ok = True
+    for path in TESTS_DIR.rglob("*.py"):
+        if not check_file(path):
+            all_ok = False
+    sys.exit(0 if all_ok else 1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/devtools/dts-check-format.sh b/devtools/dts-check-format.sh
index 907eed1293..5f93a11a16 100755
--- a/devtools/dts-check-format.sh
+++ b/devtools/dts-check-format.sh
@@ -86,7 +86,14 @@ if $lint; then
 		ruff check --fix
 		errors=$((errors + $?))
 
+		docstring_script_path=$(dirname "$0")
+		docstring_script_path=$(cd "$docstring_script_path" && pwd)
+		docstring_script="$docstring_script_path/check-docstrings.py"
+		python "$docstring_script"
+		errors=$((errors + $?))
+
 		git update-index --refresh
+
 		retval=$?
 		if [ $retval -ne 0 ]; then
 			echo 'The "needs update" files have been fixed by the linter.'
-- 
2.50.1