From: John Snow <jsnow@redhat.com>
Date: Wed, 18 Jun 2025 16:53:49 +0000 (-0400)
Subject: docs/sphinx: adjust qapidoc to cope with same-line error sections
X-Git-Tag: v10.1.0-rc0~15^2~28
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=66c83cdd91c07575ebf30bb45da8cc5df8041c29;p=thirdparty%2Fqemu.git

docs/sphinx: adjust qapidoc to cope with same-line error sections

Without this, the line the new QAPI doc generator chokes on

    # Errors: some

in doc-good.json.  We still use the old doc generator for the tests,
but we're about to correct that.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-2-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Fixes: e9fbf1a0c6c2 (docs/qapidoc: add visit_errors() method)
[Amend commit message to point to reproducer, and add Fixes:]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8011ac9efa..5374dee8fa 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -267,10 +267,14 @@ class Transmogrifier:
         self.add_field("return", typ, section.text, section.info)
 
     def visit_errors(self, section: QAPIDoc.Section) -> None:
-        # FIXME: the formatting for errors may be inconsistent and may
-        # or may not require different newline placement to ensure
-        # proper rendering as a nested list.
-        self.add_lines(f":error:\n{section.text}", section.info)
+        # If the section text does not start with a space, it means text
+        # began on the same line as the "Error:" string and we should
+        # not insert a newline in this case.
+        if section.text[0].isspace():
+            text = f":error:\n{section.text}"
+        else:
+            text = f":error: {section.text}"
+        self.add_lines(text, section.info)
 
     def preamble(self, ent: QAPISchemaDefinition) -> None:
         """