doc: dts: improve bindings-upstream

Splitting up the 'general rules' section into subsections makes it
possible to link directly to a particular rule. This is useful when
pointing out an issue during code review, sharing with another
colleague, etc. Adding a local table of contents makes the page
skimmable (it's buried too deeply in the toctree to have sections
listed in the HTML sidebar).

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>

doc/build/dts/bindings-upstream.rst

@@ -12,6 +12,9 @@ Decisions made by the Zephyr devicetree maintainer override the contents of
 this section. If that happens, though, please let them know so they can update
 this page, or you can send a patch yourself.
 
+.. contents:: Contents
+   :local:
+
 Always check for existing bindings
 **********************************
 
@@ -38,49 +41,59 @@ In particular, this rule applies if:
 General rules
 *************
 
-- Bindings which match a compatible must have file names based on the compatible.
+File names
+==========
 
-  - For example, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``.
+Bindings which match a compatible must have file names based on the compatible.
-  - If the binding is bus-specific, you can append the bus to the file name;
-    for example, if the binding YAML has ``on-bus: bar``, you may name the file
-    ``vnd,foo-bar.yaml``.
 
-- All recommendations in :ref:`dt-bindings-default` are requirements when
+- For example, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``.
-  submitting the binding.
+- If the binding is bus-specific, you can append the bus to the file name;
+  for example, if the binding YAML has ``on-bus: bar``, you may name the file
+  ``vnd,foo-bar.yaml``.
 
-  In particular, if you use the ``default:`` feature, you must justify the
+Recommendations are requirements
-  value in the property's description.
+================================
 
-- There are two ways to write property ``description:`` strings that are always
+All recommendations in :ref:`dt-bindings-default` are requirements when
-  OK.
+submitting the binding.
 
-  If your description is short, it's fine to use this style:
+In particular, if you use the ``default:`` feature, you must justify the
+value in the property's description.
 
-  .. code-block:: yaml
+Descriptions
+============
 
-     description: my short string
+There are only two acceptable ways to write property ``description:``
+strings.
 
-  If your description is long or spans multiple lines, you must use this
+If your description is short, it's fine to use this style:
-  style:
 
-  .. code-block:: yaml
+.. code-block:: yaml
 
-     description: |
+   description: my short string
-       My very long string
-       goes here.
-       Look at all these lines!
 
-  This ``|`` style prevents YAML parsers from removing the newlines in
+If your description is long or spans multiple lines, you must use this
-  multi-line descriptions. This in turn makes these long strings
+style:
-  display properly in the :ref:`devicetree_binding_index`.
 
-  Do not use any other style for long or multi-line strings.
+.. code-block:: yaml
 
-- Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
+   description: |
-  property names. Use lowercase letters (``a`` through ``z``) instead of
+     My very long string
-  uppercase. Use dashes (``-``) instead of underscores. (The one exception to
+     goes here.
-  this rule is if you are replicating a well-established binding from somewhere
+     Look at all these lines!
-  like Linux.)
+
+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`.
+
+Naming conventions
+==================
+
+Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
+property names. Use lowercase letters (``a`` through ``z``) instead of
+uppercase. Use dashes (``-``) instead of underscores. (The one exception to
+this rule is if you are replicating a well-established binding from somewhere
+like Linux.)
 
 Rules for vendor prefixes
 *************************