add complex formatting example

Set up an example directory to hold example notes and add one showing
how to use complex formatting.

Change-Id: I7b3e27c394789cc1ff832ca0bf26f3244b058eb7

doc/source/examples.rst

@@ -0,0 +1,2 @@
+.. release-notes:: Examples
+   :relnotessubdir: examples

doc/source/index.rst

@@ -17,6 +17,7 @@ Contents:
    sphinxext
    contributing
    history
+   examples
 
 Indices and tables
 ==================

doc/source/usage.rst

@@ -105,6 +105,25 @@ entirely.
    other:
      - Add other notes here, or remove this section.
 
+Formatting
+----------
+
+Release notes may include embedded reStructuredText, including simple
+inline markup like emphasis and pre-formatted text as well as complex
+body structures such as nested lists and tables. To use these
+formatting features, the note must be escaped from the YAML parser.
+
+The default template sets up the ``prelude`` section to use ``>`` so
+that line breaks in the text are removed. This escaping mechanism is
+not needed for the bullet items in the other sections of the template.
+
+To escape the text of any section and *retain* the newlines, prefix
+the value with ``|``. For example:
+
+.. include:: ../../examples/notes/add-complex-example-6b5927c246456896.yaml
+   :literal:
+
+See :doc:`examples` for the rendered version of the note.
 
 Generating a Report
 ===================

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

@@ -0,0 +1,28 @@
+---
+prelude: |
+  This paragraph will
+  retain its newlines
+  when the value is passed to the
+  reStructuredText parser, which
+  will then merge them into
+  a single paragraph without
+  breaks.
+
+  | These
+  | lines
+  | are prefixed
+  | with | so the reStructuredText
+  | parser will retain
+  | the line breaks.
+other:
+  - |
+    This bullet item includes a paragraph and a nested list.
+
+    * list item 1
+    * list item 2
+
+    ::
+
+      This example is also rendered
+      correctly on multiple lines
+      as a pre-formatted block.