John Snow <js...@redhat.com> writes:
> Sphinx does not like sections without titles, because it wants to
> convert every section into a reference. When there is no title, it
> struggles to do this and transforms the tree inproperly.
>
> Depending on the rST used, this may result in an assertion error deep in
> the docutils HTMLWriter.
>
> (Observed when using ".. admonition:: Notes" under such a section - When
> this is transformed with its own <title> element, Sphinx is fooled into
> believing this title belongs to the section and incorrect mutates the
> docutils tree, leading to errors during rendering time.)
>
> When parsing an untagged section (free paragraphs), skip making a hollow
> section and instead append the parse results to the prior section.
>
> Many Bothans died to bring us this information.
>
> Signed-off-by: John Snow <js...@redhat.com>
> ---
> docs/sphinx/qapidoc.py | 16 +++++++++++-----
> 1 file changed, 11 insertions(+), 5 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index f2f2005dd5f..66cf254a624 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -286,14 +286,20 @@ def _nodes_for_sections(self, doc):
> if section.tag and section.tag == 'TODO':
> # Hide TODO: sections
> continue
> +
> + if not section.tag:
> + # Sphinx cannot handle sectionless titles;
> + # Instead, just append the results to the prior section.
> + container = nodes.container()
> + self._parse_text_into_node(section.text, container)
> + nodelist += container.children
> + continue
> +
> snode = self._make_section(section.tag)
> - if section.tag and section.tag.startswith('Example'):
> + if section.tag.startswith('Example'):
> snode += self._nodes_for_example(dedent(section.text))
> else:
> - self._parse_text_into_node(
> - dedent(section.text) if section.tag else section.text,
> - snode,
> - )
> + self._parse_text_into_node(dedent(section.text), snode)
> nodelist.append(snode)
> return nodelist
Acked-by: Markus Armbruster <arm...@redhat.com>
