Codebase list python-reno / 8666d22
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> Doug Hellmann 6 years ago
2 changed file(s) with 27 addition(s) and 6 deletion(s). Raw diff Collapse all Expand all
+16
-1
doc/source/examples.rst less more
0 .. release-notes:: Examples
0 ==========
1 Examples
2 ==========
3
4 Input file
5 ==========
6
7 .. literalinclude:: ../../examples/notes/add-complex-example-6b5927c246456896.yaml
8 :caption: examples/notes/add-complex-example-6b5927c246456896.yaml
9 :language: yaml
10
11 Rendered
12 ========
13
14 .. release-notes::
115 :relnotessubdir: examples
16 :earliest-version: 1.0.0
+11
-5
examples/notes/add-complex-example-6b5927c246456896.yaml less more
1313 | with | so the reStructuredText
1414 | parser will retain
1515 | the line breaks.
16 features:
17 This note is a simple string, and does not retain its
18 formatting when it is rendered in HTML. rst markup here
19 may break the YAML parser, since the string is not escaped.
20 fixes:
21 - Use YAML lists to add multiple items to the same section.
22 - Another fix could be listed here.
1623 other:
1724 - |
18 This bullet item includes a paragraph and a nested list.
25 This bullet item includes a paragraph and a nested list,
26 which works because the content of the YAML list item
27 is an escaped string block with reStructuredText formatting.
1928
2029 * list item 1
2130 * list item 2
2231
23 ::
32 .. code-block:: text
2433
2534 This example is also rendered
2635 correctly on multiple lines
2736 as a pre-formatted block.
28 features:
29 This note is a simple string, and does not retain its
30 formatting when it is rendered in HTML.