From 804915841a1705442900ee8408605d348d396a83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= <benjamin@zephyrproject.org>
Date: Mon, 26 May 2025 11:57:25 +0200
Subject: [PATCH] shields: doc: allow to indicate supported hw features
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Shield authors can now indicate an optional list of hardware features
that the shield supports, in the form of the same kind of "binding type"
already used for boards.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
---
 .../zephyr/domain/templates/shield-card.html           | 10 +++++++++-
 doc/_scripts/gen_boards_catalog.py                     |  1 +
 doc/hardware/porting/shields.rst                       |  8 ++++++++
 scripts/list_shields.py                                |  4 +++-
 scripts/schemas/shield-schema.yml                      |  5 +++++
 5 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/doc/_extensions/zephyr/domain/templates/shield-card.html b/doc/_extensions/zephyr/domain/templates/shield-card.html
index 57c5a1cf043..bd6a7e892d3 100644
--- a/doc/_extensions/zephyr/domain/templates/shield-card.html
+++ b/doc/_extensions/zephyr/domain/templates/shield-card.html
@@ -13,7 +13,15 @@
   aria-label="Open the documentation page for {{ shield.full_name }}"
   data-name="{{ shield.full_name}}"
   data-vendor="{{ shield.vendor }}"
-  tabindex="0">
+  data-supported-features="
+    {%- set feature_types = [] -%}
+    {%- for feature in shield.supported_features -%}
+      {%- if feature not in feature_types -%}
+        {%- set _ = feature_types.append(feature) -%}
+      {%- endif -%}
+    {%- endfor -%}
+    {{- feature_types|join(' ') -}}
+  " tabindex="0">
   <div class="vendor">{{ vendors[shield.vendor] }}</div>
   {% if shield.image -%}
   <img alt="A picture of the {{ shield.full_name }} shield"
diff --git a/doc/_scripts/gen_boards_catalog.py b/doc/_scripts/gen_boards_catalog.py
index feb8a2ac94a..622499110bd 100755
--- a/doc/_scripts/gen_boards_catalog.py
+++ b/doc/_scripts/gen_boards_catalog.py
@@ -416,6 +416,7 @@ def get_catalog(generate_hw_features=False, hw_features_vendor_filter=None):
             "vendor": shield.vendor or "others",
             "doc_page": doc_page_path,
             "image": guess_image(shield),
+            "supported_features": shield.supported_features or [],
         }
 
     return {
diff --git a/doc/hardware/porting/shields.rst b/doc/hardware/porting/shields.rst
index b1e890f9c3c..2a0be075be9 100644
--- a/doc/hardware/porting/shields.rst
+++ b/doc/hardware/porting/shields.rst
@@ -33,6 +33,11 @@ These files provides shield configuration as follows:
   * ``name``: Name of the shield used in Kconfig and build system (required)
   * ``full_name``: Full commercial name of the shield (required)
   * ``vendor``: Manufacturer/vendor of the shield (required)
+  * ``supported_features``: List of hardware features the shield supports (optional). In order to
+    help users identify the features a shield supports without having to dig into its overlay file,
+    the ``supported_features`` field can be used to list the types of features the shield supports.
+    The values should be the same as the ones defined in the
+    :zephyr_file:`dts/bindings/binding-types.txt` file.
 
   Example:
 
@@ -41,6 +46,9 @@ These files provides shield configuration as follows:
      name: foo_shield
      full_name: Foo Shield for Arduino
      vendor: acme
+     supported_features:
+       - display
+       - input
 
 * **<shield>.overlay**: This file provides a shield description in devicetree
   format that is merged with the board's :ref:`devicetree <dt-guide>`
diff --git a/scripts/list_shields.py b/scripts/list_shields.py
index 7590fdd781d..27a84aa3004 100755
--- a/scripts/list_shields.py
+++ b/scripts/list_shields.py
@@ -39,6 +39,7 @@ class Shield:
     dir: Path
     full_name: str | None = None
     vendor: str | None = None
+    supported_features: list[str] | None = None
 
 def shield_key(shield):
     return shield.name
@@ -49,7 +50,8 @@ def process_shield_data(shield_data, shield_dir):
         name=shield_data['name'],
         dir=shield_dir,
         full_name=shield_data.get('full_name'),
-        vendor=shield_data.get('vendor')
+        vendor=shield_data.get('vendor'),
+        supported_features=shield_data.get('supported_features', []),
     )
 
 def find_shields(args):
diff --git a/scripts/schemas/shield-schema.yml b/scripts/schemas/shield-schema.yml
index b3dcba896b5..1637300228a 100644
--- a/scripts/schemas/shield-schema.yml
+++ b/scripts/schemas/shield-schema.yml
@@ -21,6 +21,11 @@ schema;shield-schema:
       required: true
       type: str
       desc: Manufacturer/vendor of the shield
+    supported_features:
+      required: false
+      sequence:
+        - type: str
+          desc: A hardware feature the shield supports (see dts/bindings/binding-types.txt)
 
 type: map
 range: