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>
This commit is contained in:
Doug Hellmann 2017-06-05 15:51:06 -04:00
parent bc3d1241dd
commit 8666d22065
2 changed files with 27 additions and 6 deletions

View File

@ -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

View File

@ -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.