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, a binding for compatible ``vnd,foo`` must be named ``vnd,foo.yaml``.
+- 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
+Recommendations are requirements
-  submitting the binding.
+================================
 
-  In particular, if you use the ``default:`` feature, you must justify the
+All recommendations in :ref:`dt-bindings-default` are requirements when
-  value in the property's description.
+submitting the binding.
 
-- There are two ways to write property ``description:`` strings that are always
+In particular, if you use the ``default:`` feature, you must justify the
-  OK.
+value in the property's description.
 
-  If your description is short, it's fine to use this style:
+Descriptions
+============
 
-  .. code-block:: yaml
+There are only two acceptable ways to write property ``description:``
+strings.
+
+If your description is short, it's fine to use this style:
+
+.. code-block:: yaml
 
    description: my short string
 
-  If your description is long or spans multiple lines, you must use this
+If your description is long or spans multiple lines, you must use this
-  style:
+style:
 
-  .. code-block:: yaml
+.. code-block:: yaml
 
    description: |
      My very long string
      goes here.
      Look at all these lines!
 
-  This ``|`` style prevents YAML parsers from removing the newlines in
+This ``|`` style prevents YAML parsers from removing the newlines in
-  multi-line descriptions. This in turn makes these long strings
+multi-line descriptions. This in turn makes these long strings
-  display properly in the :ref:`devicetree_binding_index`.
+display properly in the :ref:`devicetree_binding_index`.
 
-  Do not use any other style for long or multi-line strings.
+Naming conventions
+==================
 
-- Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
+Do not use uppercase letters (``A`` through ``Z``) or underscores (``_``) in
-  property names. Use lowercase letters (``a`` through ``z``) instead of
+property names. Use lowercase letters (``a`` through ``z``) instead of
-  uppercase. Use dashes (``-``) instead of underscores. (The one exception to
+uppercase. Use dashes (``-``) instead of underscores. (The one exception to
-  this rule is if you are replicating a well-established binding from somewhere
+this rule is if you are replicating a well-established binding from somewhere
-  like Linux.)
+like Linux.)
 
 Rules for vendor prefixes
 *************************