[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 07/21] docs/qapidoc: fix nested parsing under untagged section
From: |
John Snow |
Subject: |
[PATCH v2 07/21] docs/qapidoc: fix nested parsing under untagged sections |
Date: |
Wed, 26 Jun 2024 18:21:13 -0400 |
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 <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@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 f9683444b14..efcd84656fa 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -272,14 +272,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
--
2.45.0
- Re: [PATCH v2 03/21] docs/qapidoc: remove unused intersperse function, (continued)
- [PATCH v2 08/21] qapi: fix non-compliant JSON examples, John Snow, 2024/06/26
- [PATCH v2 09/21] qapi: nail down convention that Errors sections are lists, John Snow, 2024/06/26
- [PATCH v2 11/21] qapi: update prose in note blocks, John Snow, 2024/06/26
- [PATCH v2 10/21] qapi: convert "Note" sections to plain rST, John Snow, 2024/06/26
- [PATCH v2 12/21] qapi: add markup to note blocks, John Snow, 2024/06/26