[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 13/20] docs/qapidoc: fix nested parsing under untagged sections
From: |
John Snow |
Subject: |
[PATCH 13/20] docs/qapidoc: fix nested parsing under untagged sections |
Date: |
Tue, 14 May 2024 17:57:32 -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.
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>
---
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 34e95bd168d..cfc0cf169ef 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
--
2.44.0
[PATCH 11/20] qapi/schema: add doc_visible property to QAPISchemaDefinition, John Snow, 2024/05/14
[PATCH 15/20] qapi: remove developer factoring comments from QAPI doc blocks, John Snow, 2024/05/14
[PATCH 12/20] qapi/source: allow multi-line QAPISourceInfo advancing, John Snow, 2024/05/14
[PATCH 16/20] qapi: rewrite StatsFilter comment, John Snow, 2024/05/14
[PATCH 14/20] qapi: fix non-compliant JSON examples, John Snow, 2024/05/14
[PATCH 17/20] qapi: rewrite BlockExportOptions doc block, John Snow, 2024/05/14