edtlib: binding: Add a examples keyword

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

@@ -1,4 +1,4 @@
 # Copyright (c) 2019 Nordic Semiconductor ASA
 # Copyright (c) 2019 Linaro Limited
 # SPDX-License-Identifier: BSD-3-Clause
 
@@ -137,6 +137,17 @@
  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 @@
  "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 @@
  # 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

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: BSD-3-Clause
 
 title: Test binding
 
@@ -36,3 +36,19 @@
  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

@@ -1,4 +1,4 @@
 # Copyright (c) 2019 Nordic Semiconductor ASA
 # SPDX-License-Identifier: BSD-3-Clause
 
 import contextlib
@@ -7,6 +7,7 @@
 from logging import WARNING
 import os
 from pathlib import Path
+import textwrap
 
 import pytest
 
@@ -568,10 +569,26 @@
  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'''