Re: [PATCH v3 4/5] docs/sphinx: remove special parsing for freeform sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Fri, Jun 27, 2025, 5:52 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@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.

[...]