edtlib: binding: Add a examples keyword

Add an `examples` keyword to the binding to
provide a minimal example node for the binding.

Signed-off-by: James Roy <rruuaanng@outlook.com>

Author: rruuaanng

doc/build/dts/bindings-syntax.rst

@@ -62,6 +62,13 @@ like this:
    # bindings.
    on-bus: spi
 
+   examples:
+     # You can put a sample node here showing how to use the binding.
+     # - |
+     #  ...
+     # or
+     # - ...
+
    foo-cells:
      # "Specifier" cell names for the 'foo' domain go here; example 'foo'
      # values are 'gpio', 'pwm', and 'dma'. See below for more information.
@@ -678,6 +685,31 @@ Only ``sensor@79`` can have a ``use-clock-stretching`` property. The
 bus-sensitive logic ignores :file:`manufacturer,sensor-i2c.yaml` when searching
 for a binding for ``sensor@0``.
 
+.. _dt-bindings-examples:
+
+Examples
+********
+
+If you feel you want to provide a minimal example for your binding, you can use
+it like this:
+
+.. code-block:: yaml
+
+   description: ...
+
+   properties:
+    ...
+
+   examples:
+     - |
+       leds {
+         compatible = "gpio-leds";
+
+         uled: led {
+         gpios = <&gpioe 12 GPIO_ACTIVE_HIGH>;
+         };
+       };
+
 .. _dt-bindings-cells:
 
 Specifier cell names (\*-cells)

doc/build/dts/bindings-upstream.rst

@@ -94,6 +94,26 @@ This ``|`` style prevents YAML parsers from removing the newlines in
 multi-line descriptions. This in turn makes these long strings
 display properly in the :ref:`devicetree_binding_index`.
 
+If using the binding’s properties gets complicated, you can use examples
+to provide a minimal node. e.g.:
+
+.. code-block:: yaml
+
+   description: ...
+
+   properties:
+    ...
+
+   examples:
+     - |
+       leds {
+         compatible = "gpio-leds";
+
+         uled: led {
+         gpios = <&gpioe 12 GPIO_ACTIVE_HIGH>;
+         };
+       };
+
 Naming conventions
 ==================
 

scripts/dts/python-devicetree/src/devicetree/edtlib.py

@@ -137,6 +137,17 @@ class Binding:
       from node properties. It can also be None for Binding objects created
       using 'child-binding:' with no compatible.
 
+    examples:
+      Provides a minimal example node illustrating the binding (optional).
+      Like this:
+
+      examples:
+        - |
+          / {
+              model = "This is a sample node";
+              ...
+          };
+
     prop2specs:
       A dict mapping property names to PropertySpec objects
       describing those properties' values.
@@ -290,6 +301,11 @@ def bus(self) -> Union[None, str, list[str]]:
         "See the class docstring"
         return self.raw.get('bus')
 
+    @property
+    def examples(self) -> Optional[list[str]]:
+        "See the class docstring"
+        return self.raw.get('examples')
+
     @property
     def buses(self) -> list[str]:
         "See the class docstring"
@@ -420,7 +436,7 @@ def _check(self, require_compatible: bool, require_description: bool,
         # Allowed top-level keys. The 'include' key should have been
         # removed by _load_raw() already.
         ok_top = {"title", "description", "compatible", "bus",
-                  "on-bus", "properties", "child-binding"}
+                  "on-bus", "properties", "child-binding", "examples"}
 
         # Descriptive errors for legacy bindings.
         legacy_errors = {

scripts/dts/python-devicetree/tests/test-bindings/defaults.yaml

@@ -36,3 +36,19 @@ properties:
     type: int
     required: false
     default: 123
+
+examples:
+  - |
+    / {
+        leds {
+            compatible = "gpio-leds";
+
+            uled: led {
+                gpios = <&gpioe 12 GPIO_ACTIVE_HIGH>;
+            };
+        };
+
+        aliases {
+            led0 = &uled;
+        };
+    };

scripts/dts/python-devicetree/tests/test_edtlib.py

@@ -7,6 +7,7 @@
 from logging import WARNING
 import os
 from pathlib import Path
+import textwrap
 
 import pytest
 
@@ -568,10 +569,26 @@ def test_binding_top_key():
     title = binding.title
     description = binding.description
     compatible = binding.compatible
+    examples = binding.examples[0]
 
     assert title == "Test binding"
     assert description == "Property default value test"
     assert compatible == "defaults"
+    assert examples == textwrap.dedent("""\
+    / {
+        leds {
+            compatible = "gpio-leds";
+
+            uled: led {
+                gpios = <&gpioe 12 GPIO_ACTIVE_HIGH>;
+            };
+        };
+
+        aliases {
+            led0 = &uled;
+        };
+    };
+    """)
 
 def test_child_binding():
     '''Test 'child-binding:' in bindings'''