expand examples in documentation

Add examples showing how sections that take lists of strings can also
include a single string, and expand on why the escaped rst formatting
works.

Change-Id: I26be8c3027aebbfb1bf4a6f17c6f995dc44aac1a
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/examples.rst

@@ -1,2 +1,17 @@
-.. release-notes:: Examples
+==========
+ Examples
+==========
+
+Input file
+==========
+
+.. literalinclude:: ../../examples/notes/add-complex-example-6b5927c246456896.yaml
+   :caption: examples/notes/add-complex-example-6b5927c246456896.yaml
+   :language: yaml
+
+Rendered
+========
+
+.. release-notes::
    :relnotessubdir: examples
+   :earliest-version: 1.0.0

examples/notes/add-complex-example-6b5927c246456896.yaml

@@ -14,18 +14,24 @@ prelude: |
   | with | so the reStructuredText
   | parser will retain
   | the line breaks.
+features:
+  This note is a simple string, and does not retain its
+  formatting when it is rendered in HTML. rst markup here
+  may break the YAML parser, since the string is not escaped.
+fixes:
+  - Use YAML lists to add multiple items to the same section.
+  - Another fix could be listed here.
 other:
   - |
-    This bullet item includes a paragraph and a nested list.
+    This bullet item includes a paragraph and a nested list,
+    which works because the content of the YAML list item
+    is an escaped string block with reStructuredText formatting.
 
     * list item 1
     * list item 2
 
-    ::
+    .. code-block:: text
 
       This example is also rendered
       correctly on multiple lines
       as a pre-formatted block.
-features:
-  This note is a simple string, and does not retain its
-  formatting when it is rendered in HTML.