John Snow <js...@redhat.com> writes:
> On Fri, Jun 27, 2025, 5:52 AM Markus Armbruster <arm...@redhat.com> wrote:
>
>> John Snow <js...@redhat.com> writes:
>>
>> > This change removes special parsing for freeform sections and allows
>> > them to simply be unmodified rST syntax. The existing headings in the
>> > QAPI schema are adjusted to reflect the new paradigm.
>>
>> "Allows them to" suggests the patch enables use of rST headings. Is
>> this the case? Or do they just work, and this patch just switches
>> schema code to use them, and drops now unnecessary generator code?
>>
>
> Ehm... Kind of both? I guess I hadn't considered that rST headings might
> already work without the switch. I guess they didn't because of the
> headerless freeform section bug I fix in this series.
To double-check master, I use
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 14b808f909..201462688f 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -8,7 +8,9 @@
'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } }
##
-# = Section
+# *******
+# Section
+# *******
##
##
Doesn't work with the legacy doc generator:
Exception occurred:
File "/work/armbru/qemu/docs/sphinx/qapidoc_legacy.py", line 360, in
_start_new_heading
raise QAPISemError(self._cur_doc.info,
...<2 lines>...
% (level, level - 1))
qapi.error.QAPISemError:
/work/armbru/qemu/docs/../tests/qapi-schema/doc-good.json:20: Level 2
subheading found outside a level 1 heading
So switch to the new one:
diff --git a/tests/qapi-schema/doc-good.rst b/tests/qapi-schema/doc-good.rst
index 1e4c23305a..9978ac2e9c 100644
--- a/tests/qapi-schema/doc-good.rst
+++ b/tests/qapi-schema/doc-good.rst
@@ -3,3 +3,4 @@
a plain-text output file and compare it against a reference.
.. qapi-doc:: tests/qapi-schema/doc-good.json
+ :transmogrify:
Chokes on "# Errors: some", you fix this (unrelated) bug in PATCH 1. I
could apply that fix, but instead I simply work around the bug:
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 14b808f909..201462688f 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -165,7 +167,8 @@
#
# Returns: @Object
#
-# Errors: some
+# Errors:
+# some
#
# TODO: frobnicate
#
The rST heading seems to work fine then.
The next-level heading
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 14b808f9090..fac13425b72 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -16,7 +18,8 @@
##
##
-# == Subsection
+# Subsection
+# ==========
#
# *with emphasis*
# @var {in braces}
doesn't:
Extension error:
/work/armbru/qemu/docs/../tests/qapi-schema/doc-good.json:22:1: '=' heading
must come first in a comment block
Removed in this patch.
So you're right, "kind of both": they work just fine with the new doc
generator, except for the "====" rST headings, because the parser still
recognizes them as old-style schema doc headings.
> I guess you're technically right, I just never thought of it in that way.
>
> I'll update the message so I don't confuse you in the future.
Yes, please.
[...]
