shields: doc: allow to indicate supported hw features

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>

Author: kartben

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"

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 {

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>`

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):

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: