Skip to contentSkip to conversation

docs: remove legacy qapidoc

PATCH Applied John Snow 2 participants 18 messages Jun 18, 2025 – Jul 14, 2025 Arm/Amlogic Meson SoC support

lore
Share & tools
lore

John Snow

author
#0 lore raw

v3 cover docs: remove legacy qapidoc

Remove docs/sphinx/qapidoc_legacy.py, and remove special parsing of freeform QAPI documentation block sections in favor of using standard rST syntax that is included in the final document with no special parsing or post-processing.

v3:
- Fixed indentation for :error: in qapidoc
- Removed parser restrictions on QAPI-style headers
- Updated test output so make check passes ...

v2:
- rebased on origin/master (2025-06-12)
- Revised commit messages with increased detail

John Snow (5):
docs/sphinx: adjust qapidoc to cope with same-line error sections docs/sphinx: parse @references in freeform text docs/sphinx: remove legacy QAPI manual generator docs/sphinx: remove special parsing for freeform sections
qapi: lift restriction on using '=' in doc blocks

 docs/devel/qapi-code-gen.rst                 |  28 +-
 docs/interop/firmware.json                   |   4 +-
 docs/interop/qemu-ga-ref.rst                 |   1 -
 docs/interop/qemu-qmp-ref.rst                |   1 -
 docs/interop/qemu-storage-daemon-qmp-ref.rst |   1 -
 docs/interop/vhost-user.json                 |   4 +-
 docs/sphinx/qapidoc.py                       |  82 +---
 docs/sphinx/qapidoc_legacy.py                | 440 -------------------
 qapi/acpi.json                               |   4 +-
 qapi/audio.json                              |   4 +-
 qapi/authz.json                              |   4 +-
 qapi/block-core.json                         |   3 +-
 qapi/block-export.json                       |   3 +-
 qapi/block.json                              |   7 +-
 qapi/char.json                               |   4 +-
 qapi/common.json                             |   4 +-
 qapi/compat.json                             |   4 +-
 qapi/control.json                            |   4 +-
 qapi/crypto.json                             |   4 +-
 qapi/cryptodev.json                          |   4 +-
 qapi/cxl.json                                |   4 +-
 qapi/dump.json                               |   4 +-
 qapi/ebpf.json                               |   4 +-
 qapi/error.json                              |   4 +-
 qapi/introspect.json                         |   4 +-
 qapi/job.json                                |   4 +-
 qapi/machine-common.json                     |   4 +-
 qapi/machine.json                            |   4 +-
 qapi/migration.json                          |   4 +-
 qapi/misc.json                               |   4 +-
 qapi/net.json                                |   4 +-
 qapi/pci.json                                |   4 +-
 qapi/qapi-schema.json                        |   4 +-
 qapi/qdev.json                               |   4 +-
 qapi/qom.json                                |   4 +-
 qapi/replay.json                             |   4 +-
 qapi/rocker.json                             |   4 +-
 qapi/run-state.json                          |   4 +-
 qapi/sockets.json                            |   4 +-
 qapi/stats.json                              |   4 +-
 qapi/tpm.json                                |   4 +-
 qapi/trace.json                              |   4 +-
 qapi/transaction.json                        |   4 +-
 qapi/uefi.json                               |   4 +-
 qapi/ui.json                                 |  14 +-
 qapi/vfio.json                               |   4 +-
 qapi/virtio.json                             |   4 +-
 qapi/yank.json                               |   4 +-
 python/tests/qapi-isort.sh                   |   2 +-
 scripts/qapi/parser.py                       |  11 -
 storage-daemon/qapi/qapi-schema.json         |   8 +-
 tests/qapi-schema/doc-bad-section.err        |   1 -
 tests/qapi-schema/doc-bad-section.json       |  10 -
 tests/qapi-schema/doc-bad-section.out        |   0
 tests/qapi-schema/doc-good.json              |  10 +-
 tests/qapi-schema/doc-good.out               |  10 +-
 tests/qapi-schema/doc-good.txt               | 274 ++++--------
 tests/qapi-schema/meson.build                |   1 -
 58 files changed, 275 insertions(+), 784 deletions(-)
 delete mode 100644 docs/sphinx/qapidoc_legacy.py
 delete mode 100644 tests/qapi-schema/doc-bad-section.err
 delete mode 100644 tests/qapi-schema/doc-bad-section.json
 delete mode 100644 tests/qapi-schema/doc-bad-section.out
Signature · 1 line
2.48.1
author
#1 lore raw

PATCH v3 1/5 docs/sphinx: adjust qapidoc to cope with same-line error sections

---
 docs/sphinx/qapidoc.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)
docs/sphinx/qapidoc.py +8 -4
index 8011ac9efaf..5374dee8fad 100644
@@ -267,10 +267,14 @@ def visit_returns(self, section: QAPIDoc.Section) -> None:
         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:
         """
Signature · 1 line
2.48.1
#2 lore raw

Re: [PATCH v3 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections

Quoted 1 line · John Snow

Let's mention the reproducer: "# Errors: some" in doc-good.json with :transmogrify:.

Quoted 27 lines
---
 docs/sphinx/qapidoc.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)
docs/sphinx/qapidoc.py +8 -4
index 8011ac9efaf..5374dee8fad 100644
@@ -267,10 +267,14 @@ def visit_returns(self, section: QAPIDoc.Section) -> None:
         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:
         """
#3 lore raw

Re: [PATCH v3 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections

Quoted 6 lines · Markus Armbruster
Quoted 1 line · John Snow

Let's mention the reproducer: "# Errors: some" in doc-good.json with :transmogrify:.

I'm adding

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.

and

Fixes e9fbf1a0c6c2 (docs/qapidoc: add visit_errors() method)
author
#4 lore raw

PATCH v3 2/5 docs/sphinx: parse @references in freeform text

In reply to John Snow

Oversight in the new qapidoc transmogrifier: @references in freeform documentation blocks were not being transformed to literals. This fixes that, and the next patch ensures that we're testing for this O:-)

---
 docs/sphinx/qapidoc.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
docs/sphinx/qapidoc.py +7 -3
index 5374dee8fad..adc14ade456 100644
@@ -218,6 +218,11 @@ def generate_field(
         typ = self.format_type(member)
         self.add_field(kind, member.name, body, info, typ)
 
+    @staticmethod
+    def reformat_arobase(text: str) -> str:
+        """ reformats @var to ``var`` """
+        return re.sub(r"@([\w-]+)", r"``\1``", text)
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
 
         # Add sections in source order:
         for i, section in enumerate(sections):
-            # @var is translated to ``var``:
-            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
+            section.text = self.reformat_arobase(section.text)
 
             if section.kind == QAPIDoc.Kind.PLAIN:
                 self.visit_paragraph(section)
@@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
 
         assert len(doc.all_sections) == 1, doc.all_sections
         body = doc.all_sections[0]
-        text = body.text
+        text = self.reformat_arobase(body.text)
         info = doc.info
 
         if re.match(r"=+ ", text):
Signature · 1 line
2.48.1
#5 lore raw

Re: [PATCH v3 2/5] docs/sphinx: parse @references in freeform text

Quoted 14 lines · John Snow

Oversight in the new qapidoc transmogrifier: @references in freeform documentation blocks were not being transformed to literals. This fixes that, and the next patch ensures that we're testing for this O:-)

---
 docs/sphinx/qapidoc.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
docs/sphinx/qapidoc.py +0 -0
index 5374dee8fad..adc14ade456 100644

docs/sphinx/qapidoc.py def generate_field( · line 222

Quoted 5 lines
docs/sphinx/qapidoc.py +2 -0
@@ -218,6 +218,11 @@ def generate_field(
         typ = self.format_type(member)
         self.add_field(kind, member.name, body, info, typ)
 
+    @staticmethod
+    def reformat_arobase(text: str) -> str:

What's an "arobase"? Inquiring mind wants to know!

Quoted 25 lines
docs/sphinx/qapidoc.py +5 -3
+        """ reformats @var to ``var`` """
+        return re.sub(r"@([\w-]+)", r"``\1``", text)
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
 
         # Add sections in source order:
         for i, section in enumerate(sections):
-            # @var is translated to ``var``:
-            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
+            section.text = self.reformat_arobase(section.text)
 
             if section.kind == QAPIDoc.Kind.PLAIN:
                 self.visit_paragraph(section)
@@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
 
         assert len(doc.all_sections) == 1, doc.all_sections
         body = doc.all_sections[0]
-        text = body.text
+        text = self.reformat_arobase(body.text)
         info = doc.info
 
         if re.match(r"=+ ", text):
author
#6 lore raw

Re: [PATCH v3 2/5] docs/sphinx: parse @references in freeform text

Quoted 19 lines · Markus Armbruster
Quoted 17 lines · John Snow

Oversight in the new qapidoc transmogrifier: @references in freeform documentation blocks were not being transformed to literals. This fixes that, and the next patch ensures that we're testing for this O:-)

---
 docs/sphinx/qapidoc.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
docs/sphinx/qapidoc.py +0 -0
index 5374dee8fad..adc14ade456 100644
@@ -218,6 +218,11 @@ def generate_field(
         typ = self.format_type(member)
         self.add_field(kind, member.name, body, info, typ)
 
Quoted 5 lines

docs/sphinx/qapidoc.py def generate_field( · line 222

Quoted 2 lines
docs/sphinx/qapidoc.py +2 -0
+    @staticmethod
+    def reformat_arobase(text: str) -> str:

What's an "arobase"? Inquiring mind wants to know!

French for "at symbol thingie" :)

(Intentionally obtuse as an oblique joke, forgive my humor)

Quoted 28 lines

docs/sphinx/qapidoc.py def visit_sections(self, ent: QAPISchemaDefinition)

Quoted 7 lines
docs/sphinx/qapidoc.py +3 -0
+        """ reformats @var to ``var`` """
+        return re.sub(r"@([\w-]+)", r"``\1``", text)
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition)

-> None:

Quoted 18 lines
docs/sphinx/qapidoc.py +2 -3
         # Add sections in source order:
         for i, section in enumerate(sections):
-            # @var is translated to ``var``:
-            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
+            section.text = self.reformat_arobase(section.text)
 
             if section.kind == QAPIDoc.Kind.PLAIN:
                 self.visit_paragraph(section)
@@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
 
         assert len(doc.all_sections) == 1, doc.all_sections
         body = doc.all_sections[0]
-        text = body.text
+        text = self.reformat_arobase(body.text)
         info = doc.info
 
         if re.match(r"=+ ", text):
author
#7 lore raw

PATCH v3 3/5 docs/sphinx: remove legacy QAPI manual generator

In reply to John Snow

Thanks for your service!

Remove the old qapidoc and the option to enable the transmogrifier, leaving the "transmogrifier" as the ONLY qapi doc generator. This in effect also converts the QAPI test to use the new documentation generator, too.

Update doc-good.txt output to match the new doc generator, which I should've done exactly when we switched over to the transmogrifier, but, uhh, oops!

Notes on the new format:
1. per-member IFCOND documentation is missing. Known issue.
2. Freeform documentation without a header is now copied through into the output. This is an intentional change.

---
 docs/interop/qemu-ga-ref.rst                 |   1 -
 docs/interop/qemu-qmp-ref.rst                |   1 -
 docs/interop/qemu-storage-daemon-qmp-ref.rst |   1 -
 docs/sphinx/qapidoc.py                       |  25 +-
 docs/sphinx/qapidoc_legacy.py                | 440 -------------------
 python/tests/qapi-isort.sh                   |   2 +-
 tests/qapi-schema/doc-good.txt               | 274 ++++--------
 7 files changed, 88 insertions(+), 656 deletions(-)
 delete mode 100644 docs/sphinx/qapidoc_legacy.py
docs/interop/qemu-ga-ref.rst +0 -1
index 25f6e24b03c..ea6652ae43e 100644
@@ -2,5 +2,4 @@ QEMU Guest Agent Protocol Reference
 ===================================
 
 .. qapi-doc:: qga/qapi-schema.json
-   :transmogrify:
    :namespace: QGA
docs/interop/qemu-qmp-ref.rst +0 -1
index 3bc1ca12b16..f0ce39ad67d 100644
@@ -7,5 +7,4 @@ QEMU QMP Reference Manual
    :local:
 
 .. qapi-doc:: qapi/qapi-schema.json
-   :transmogrify:
    :namespace: QMP
docs/interop/qemu-storage-daemon-qmp-ref.rst +0 -1
index dc7bde262ae..4dbb6a2cc83 100644
@@ -5,5 +5,4 @@ QEMU Storage Daemon QMP Reference Manual
    :local:
 
 .. qapi-doc:: storage-daemon/qapi/qapi-schema.json
-   :transmogrify:
    :namespace: QSD
docs/sphinx/qapidoc.py +1 -24
index adc14ade456..d5d2b5eeb50 100644
@@ -64,8 +64,6 @@
 from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.nodes import nested_parse_with_titles
 
-from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
-
 
 if TYPE_CHECKING:
     from typing import (
@@ -512,15 +510,9 @@ class QAPIDocDirective(NestedDirective):
     option_spec = {
         "qapifile": directives.unchanged_required,
         "namespace": directives.unchanged,
-        "transmogrify": directives.flag,
     }
     has_content = False
 
-    def new_serialno(self) -> str:
-        """Return a unique new ID string suitable for use as a node's ID"""
-        env = self.state.document.settings.env
-        return "qapidoc-%d" % env.new_serialno("qapidoc")
-
     def transmogrify(self, schema: QAPISchema) -> nodes.Element:
         logger.info("Transmogrifying QAPI to rST ...")
         vis = Transmogrifier()
@@ -598,21 +590,10 @@ def write_intermediate(self, content: StringList, filename: str) -> None:
                     outfile.write(f" {rcol}")
                 outfile.write("\n")
 
-    def legacy(self, schema: QAPISchema) -> nodes.Element:
-        vis = QAPISchemaGenRSTVisitor(self)
-        vis.visit_begin(schema)
-        for doc in schema.docs:
-            if doc.symbol:
-                vis.symbol(doc, schema.lookup_entity(doc.symbol))
-            else:
-                vis.freeform(doc)
-        return vis.get_document_node()  # type: ignore
-
     def run(self) -> Sequence[nodes.Node]:
         env = self.state.document.settings.env
         qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
         qapidir = os.path.dirname(qapifile)
-        transmogrify = "transmogrify" in self.options
 
         try:
             schema = QAPISchema(qapifile)
@@ -625,11 +606,7 @@ def run(self) -> Sequence[nodes.Node]:
             # so they are displayed nicely to the user
             raise ExtensionError(str(err)) from err
 
-        if transmogrify:
-            contentnode = self.transmogrify(schema)
-        else:
-            contentnode = self.legacy(schema)
-
+        contentnode = self.transmogrify(schema)
         return contentnode.children
 
 
docs/sphinx/qapidoc_legacy.py deleted +0 -440

440 lines not on this page · raw message

python/tests/qapi-isort.sh +1 -1
index 78dd947f68c..067c16d5d94 100755
@@ -3,6 +3,6 @@
 
 python3 -m isort --sp . -c ../scripts/qapi/
 # Force isort to recognize "compat" as a local module and not third-party
-python3 -m isort --sp . -c -p compat -p qapidoc_legacy \
+python3 -m isort --sp . -c -p compat \
         ../docs/sphinx/qapi_domain.py \
         ../docs/sphinx/qapidoc.py
tests/qapi-schema/doc-good.txt +86 -188

341 lines not on this page · raw message

Signature · 1 line
2.48.1
#8 lore raw

Re: [PATCH v3 3/5] docs/sphinx: remove legacy QAPI manual generator

Quoted 7 lines · John Snow

Thanks for your service!

Remove the old qapidoc and the option to enable the transmogrifier, leaving the "transmogrifier" as the ONLY qapi doc generator. This in effect also converts the QAPI test to use the new documentation generator, too.

Quoted 9 lines

Update doc-good.txt output to match the new doc generator, which I should've done exactly when we switched over to the transmogrifier, but, uhh, oops!

Notes on the new format:
1. per-member IFCOND documentation is missing. Known issue.
2. Freeform documentation without a header is now copied through into the output. This is an intentional change.

Make that "This is a bug fix", and add

Fixes b61a4eb3f32 (docs/qapidoc: support header-less freeform sections)
Quoted 1 line
author
#9 lore raw

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

In reply to John Snow

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.

Tests and documentation are updated to match.

---
 docs/devel/qapi-code-gen.rst         | 28 ++++++++++++++-------
 docs/interop/firmware.json           |  4 ++-
 docs/interop/vhost-user.json         |  4 ++-
 docs/sphinx/qapidoc.py               | 37 +---------------------------
 qapi/acpi.json                       |  4 ++-
 qapi/audio.json                      |  4 ++-
 qapi/authz.json                      |  4 ++-
 qapi/block-core.json                 |  3 ++-
 qapi/block-export.json               |  3 ++-
 qapi/block.json                      |  7 ++++--
 qapi/char.json                       |  4 ++-
 qapi/common.json                     |  4 ++-
 qapi/compat.json                     |  4 ++-
 qapi/control.json                    |  4 ++-
 qapi/crypto.json                     |  4 ++-
 qapi/cryptodev.json                  |  4 ++-
 qapi/cxl.json                        |  4 ++-
 qapi/dump.json                       |  4 ++-
 qapi/ebpf.json                       |  4 ++-
 qapi/error.json                      |  4 ++-
 qapi/introspect.json                 |  4 ++-
 qapi/job.json                        |  4 ++-
 qapi/machine-common.json             |  4 ++-
 qapi/machine.json                    |  4 ++-
 qapi/migration.json                  |  4 ++-
 qapi/misc.json                       |  4 ++-
 qapi/net.json                        |  4 ++-
 qapi/pci.json                        |  4 ++-
 qapi/qapi-schema.json                |  4 ++-
 qapi/qdev.json                       |  4 ++-
 qapi/qom.json                        |  4 ++-
 qapi/replay.json                     |  4 ++-
 qapi/rocker.json                     |  4 ++-
 qapi/run-state.json                  |  4 ++-
 qapi/sockets.json                    |  4 ++-
 qapi/stats.json                      |  4 ++-
 qapi/tpm.json                        |  4 ++-
 qapi/trace.json                      |  4 ++-
 qapi/transaction.json                |  4 ++-
 qapi/uefi.json                       |  4 ++-
 qapi/ui.json                         | 14 ++++++++---
 qapi/vfio.json                       |  4 ++-
 qapi/virtio.json                     |  4 ++-
 qapi/yank.json                       |  4 ++-
 scripts/qapi/parser.py               |  7 ------
 storage-daemon/qapi/qapi-schema.json |  8 ++++--
 tests/qapi-schema/doc-good.json      | 10 +++++---
 tests/qapi-schema/doc-good.out       | 10 +++++---
 48 files changed, 173 insertions(+), 106 deletions(-)
docs/devel/qapi-code-gen.rst +19 -9
index 231cc0fecf7..dfdbeac5a5a 100644
@@ -876,25 +876,35 @@ structuring content.
 Headings and subheadings
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-A free-form documentation comment containing a line which starts with
-some ``=`` symbols and then a space defines a section heading::
+Free-form documentation does not start with ``@SYMBOL`` and can contain
+arbitrary rST markup. Headings can be marked up using the standard rST
+syntax::
 
     ##
-    # = This is a top level heading
+    # *************************
+    # This is a level 2 heading
+    # *************************
     #
     # This is a free-form comment which will go under the
     # top level heading.
     ##
 
     ##
-    # == This is a second level heading
+    # This is a third level heading
+    # ==============================
+    #
+    # Level 4
+    # _______
+    #
+    # Level 5
+    # ^^^^^^^
+    #
+    # Level 6
+    # """""""
     ##
 
-A heading line must be the first line of the documentation
-comment block.
-
-Section headings must always be correctly nested, so you can only
-define a third-level heading inside a second-level heading, and so on.
+Level 1 headings are reserved for use by the generated documentation
+page itself, leaving level 2 as the highest level that should be used.
 
 
 Documentation markup
docs/interop/firmware.json +3 -1
index 745d21d8223..f46fdedfa89 100644
@@ -11,7 +11,9 @@
 # later. See the COPYING file in the top-level directory.
 
 ##
-# = Firmware
+# ********
+# Firmware
+# ********
 ##
 
 { 'pragma': {
docs/interop/vhost-user.json +3 -1
index b6ade9e4931..095eb99cf79 100644
@@ -10,7 +10,9 @@
 # later. See the COPYING file in the top-level directory.
 
 ##
-# = vhost user backend discovery & capabilities
+# *******************************************
+# vhost user backend discovery & capabilities
+# *******************************************
 ##
 
 ##
docs/sphinx/qapidoc.py +1 -36
index d5d2b5eeb50..b794cde6971 100644
@@ -399,44 +399,9 @@ def visit_module(self, path: str) -> None:
         self.ensure_blank_line()
 
     def visit_freeform(self, doc: QAPIDoc) -> None:
-        # TODO: Once the old qapidoc transformer is deprecated, freeform
-        # sections can be updated to pure rST, and this transformed removed.
-        #
-        # For now, translate our micro-format into rST. Code adapted
-        # from Peter Maydell's freeform().
-
         assert len(doc.all_sections) == 1, doc.all_sections
         body = doc.all_sections[0]
-        text = self.reformat_arobase(body.text)
-        info = doc.info
-
-        if re.match(r"=+ ", text):
-            # Section/subsection heading (if present, will always be the
-            # first line of the block)
-            (heading, _, text) = text.partition("\n")
-            (leader, _, heading) = heading.partition(" ")
-            # Implicit +1 for heading in the containing .rst doc
-            level = len(leader) + 1
-
-            # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
-            markers = ' #*=_^"'
-            overline = level <= 2
-            marker = markers[level]
-
-            self.ensure_blank_line()
-            # This credits all 2 or 3 lines to the single source line.
-            if overline:
-                self.add_line(marker * len(heading), info)
-            self.add_line(heading, info)
-            self.add_line(marker * len(heading), info)
-            self.ensure_blank_line()
-
-            # Eat blank line(s) and advance info
-            trimmed = text.lstrip("\n")
-            text = trimmed
-            info = info.next_line(len(text) - len(trimmed) + 1)
-
-        self.add_lines(text, info)
+        self.add_lines(self.reformat_arobase(body.text), doc.info)
         self.ensure_blank_line()
 
     def visit_entity(self, ent: QAPISchemaDefinition) -> None:
qapi/acpi.json +3 -1
index 2d53b823656..90f8f564fda 100644
@@ -6,7 +6,9 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 ##
-# = ACPI
+# ****
+# ACPI
+# ****
 ##
 
 ##
qapi/audio.json +3 -1
index 16de231f6d8..6a22ca384aa 100644
@@ -7,7 +7,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Audio
+# *****
+# Audio
+# *****
 ##
 
 ##
qapi/authz.json +3 -1
index 7fc6e3032ea..ad1b4b3af0c 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = User authorization
+# ******************
+# User authorization
+# ******************
 ##
 
 ##
qapi/block-core.json +2 -1
index 1df6644f0de..8b413946ff8 100644
@@ -2,7 +2,8 @@
 # vim: filetype=python
 
 ##
-# == Block core (VM unrelated)
+# Block core (VM unrelated)
+# =========================
 ##
 
 { 'include': 'common.json' }
qapi/block-export.json +2 -1
index ed4deb54db2..2241bfecf25 100644
@@ -2,7 +2,8 @@
 # vim: filetype=python
 
 ##
-# == Block device exports
+# Block device exports
+# ====================
 ##
 
 { 'include': 'sockets.json' }
qapi/block.json +5 -2
index 1490a1a17f8..2d54a81c366 100644
@@ -2,13 +2,16 @@
 # vim: filetype=python
 
 ##
-# = Block devices
+# *************
+# Block devices
+# *************
 ##
 
 { 'include': 'block-core.json' }
 
 ##
-# == Additional block stuff (VM related)
+# Additional block stuff (VM related)
+# ===================================
 ##
 
 ##
qapi/char.json +3 -1
index df6e325e2e1..f38d04986dd 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Character devices
+# *****************
+# Character devices
+# *****************
 ##
 
 { 'include': 'sockets.json' }
qapi/common.json +3 -1
index 0e3a0bbbfb0..af7e3d618a7 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = Common data types
+# *****************
+# Common data types
+# *****************
 ##
 
 ##
qapi/compat.json +3 -1
index 42034d9368c..90b8d51cf27 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = Compatibility policy
+# ********************
+# Compatibility policy
+# ********************
 ##
 
 ##
qapi/control.json +3 -1
index 34b733f63b6..ab0b3a3bbe5 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = QMP monitor control
+# *******************
+# QMP monitor control
+# *******************
 ##
 
 ##
qapi/crypto.json +3 -1
index 9ec6301e188..21006de36c4 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Cryptography
+# ************
+# Cryptography
+# ************
 ##
 
 ##
qapi/cryptodev.json +3 -1
index b13db264034..1f49e1822c0 100644
@@ -5,7 +5,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Cryptography devices
+# ********************
+# Cryptography devices
+# ********************
 ##
 
 ##
qapi/cxl.json +3 -1
index 8f2e9237b19..52cc5d4f336 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = CXL devices
+# ***********
+# CXL devices
+# ***********
 ##
 
 ##
qapi/dump.json +3 -1
index d0ba1f0596f..0642ca157b8 100644
@@ -5,7 +5,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Dump guest memory
+# *****************
+# Dump guest memory
+# *****************
 ##
 
 ##
qapi/ebpf.json +3 -1
index db19ae850fc..d45054e6663 100644
@@ -5,7 +5,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = eBPF Objects
+# ************
+# eBPF Objects
+# ************
 #
 # eBPF object is an ELF binary that contains the eBPF program and eBPF
 # map description(BTF).  Overall, eBPF object should contain the
qapi/error.json +3 -1
index 135c1e82319..54cb02fb880 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = QMP errors
+# **********
+# QMP errors
+# **********
 ##
 
 ##
qapi/introspect.json +3 -1
index e9e02972821..26d8839f19c 100644
@@ -10,7 +10,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = QMP introspection
+# *****************
+# QMP introspection
+# *****************
 ##
 
 ##
qapi/job.json +3 -1
index 126fa5ce602..16b280f52f8 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = Background jobs
+# ***************
+# Background jobs
+# ***************
 ##
 
 ##
qapi/machine-common.json +3 -1
index 298e51f373a..0f01599130c 100644
@@ -5,7 +5,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Common machine types
+# ********************
+# Common machine types
+# ********************
 ##
 
 ##
qapi/machine.json +3 -1
index 0650b8de71a..6ebb99dfabe 100644
@@ -5,7 +5,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Machines
+# ********
+# Machines
+# ********
 ##
 
 { 'include': 'common.json' }
qapi/migration.json +3 -1
index 4963f6ca127..84f4c800f7b 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Migration
+# *********
+# Migration
+# *********
 ##
 
 { 'include': 'common.json' }
qapi/misc.json +3 -1
index 4b9e601cfa5..a180c16db25 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Miscellanea
+# ***********
+# Miscellanea
+# ***********
 ##
 
 { 'include': 'common.json' }
qapi/net.json +3 -1
index 97ea1839813..3b03843c165 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Net devices
+# ***********
+# Net devices
+# ***********
 ##
 
 { 'include': 'sockets.json' }
qapi/pci.json +3 -1
index dc85a41d28b..a8671cd9ac3 100644
@@ -6,7 +6,9 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 ##
-# = PCI
+# ***
+# PCI
+# ***
 ##
 
 ##
qapi/qapi-schema.json +3 -1
index a8f66163cb7..49b9a0267d3 100644
@@ -1,7 +1,9 @@
 # -*- Mode: Python -*-
 # vim: filetype=python
 ##
-# = Introduction
+# ************
+# Introduction
+# ************
 #
 # This manual describes the commands and events supported by the QEMU
 # Monitor Protocol (QMP).
qapi/qdev.json +3 -1
index 32c7d100463..441ed518b87 100644
@@ -5,7 +5,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Device infrastructure (qdev)
+# ****************************
+# Device infrastructure (qdev)
+# ****************************
 ##
 
 { 'include': 'qom.json' }
qapi/qom.json +3 -1
index 3e8debf78c2..c8fe0258a5f 100644
@@ -10,7 +10,9 @@
 { 'include': 'crypto.json' }
 
 ##
-# = QEMU Object Model (QOM)
+# ***********************
+# QEMU Object Model (QOM)
+# ***********************
 ##
 
 ##
qapi/replay.json +3 -1
index 35e0c4a6926..e46c5c1d3f3 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Record/replay
+# *************
+# Record/replay
+# *************
 ##
 
 { 'include': 'common.json' }
qapi/rocker.json +3 -1
index 0c7ef1f77c8..e4949649526 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = Rocker switch device
+# ********************
+# Rocker switch device
+# ********************
 ##
 
 ##
qapi/run-state.json +3 -1
index fd09beb35cb..083a3c5eb30 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = VM run state
+# ************
+# VM run state
+# ************
 ##
 
 ##
qapi/sockets.json +3 -1
index f9f559dabae..b5f4a8fecda 100644
@@ -2,7 +2,9 @@
 # vim: filetype=python
 
 ##
-# = Socket data types
+# *****************
+# Socket data types
+# *****************
 ##
 
 ##
qapi/stats.json +3 -1
index 8902ef94e08..78b88881eab 100644
@@ -9,7 +9,9 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 ##
-# = Statistics
+# **********
+# Statistics
+# **********
 ##
 
 ##
qapi/tpm.json +3 -1
index a16a72edb98..e66b107f1d0 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = TPM (trusted platform module) devices
+# *************************************
+# TPM (trusted platform module) devices
+# *************************************
 ##
 
 ##
qapi/trace.json +3 -1
index eb5f63f5135..d08c9c6a889 100644
@@ -7,7 +7,9 @@
 # See the COPYING file in the top-level directory.
 
 ##
-# = Tracing
+# *******
+# Tracing
+# *******
 ##
 
 ##
qapi/transaction.json +3 -1
index 9d9e7af26cb..927035f5a7e 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Transactions
+# ************
+# Transactions
+# ************
 ##
 
 { 'include': 'block-core.json' }
qapi/uefi.json +3 -1
index 6592183d6cf..a206c2e9539 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = UEFI Variable Store
+# *******************
+# UEFI Variable Store
+# *******************
 #
 # The QEMU efi variable store implementation (hw/uefi/) uses this to
 # store non-volatile variables in json format on disk.
qapi/ui.json +10 -4
index 514fa159b10..f5e77ae19d7 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Remote desktop
+# **************
+# Remote desktop
+# **************
 ##
 
 { 'include': 'common.json' }
@@ -200,7 +202,8 @@
   'if': 'CONFIG_PIXMAN' }
 
 ##
-# == Spice
+# Spice
+# =====
 ##
 
 ##
@@ -461,7 +464,8 @@
   'if': 'CONFIG_SPICE' }
 
 ##
-# == VNC
+# VNC
+# ===
 ##
 
 ##
@@ -794,7 +798,9 @@
   'if': 'CONFIG_VNC' }
 
 ##
-# = Input
+# *****
+# Input
+# *****
 ##
 
 ##
qapi/vfio.json +3 -1
index b53b7caecd7..a1a9c5b673d 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = VFIO devices
+# ************
+# VFIO devices
+# ************
 ##
 
 ##
qapi/virtio.json +3 -1
index 73df718a261..3cac0774f7a 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Virtio devices
+# **************
+# Virtio devices
+# **************
 ##
 
 ##
qapi/yank.json +3 -1
index 30f46c97c98..d13a8e91171 100644
@@ -3,7 +3,9 @@
 #
 
 ##
-# = Yank feature
+# ************
+# Yank feature
+# ************
 ##
 
 ##
scripts/qapi/parser.py +0 -7
index 949d9e8bff7..aad7e249f86 100644
@@ -597,22 +597,15 @@ def get_doc(self) -> 'QAPIDoc':
             # Free-form documentation
             doc = QAPIDoc(info)
             doc.ensure_untagged_section(self.info)
-            first = True
             while line is not None:
                 if match := self._match_at_name_colon(line):
                     raise QAPIParseError(
                         self,
                         "'@%s:' not allowed in free-form documentation"
                         % match.group(1))
-                if line.startswith('='):
-                    if not first:
-                        raise QAPIParseError(
-                            self,
-                            "'=' heading must come first in a comment block")
                 doc.append_line(line)
                 self.accept(False)
                 line = self.get_doc_line()
-                first = False
 
         self.accept()
         doc.end()
storage-daemon/qapi/qapi-schema.json +6 -2
index 0427594c984..478e7a92b21 100644
@@ -14,7 +14,9 @@
 # storage daemon.
 
 ##
-# = Introduction
+# ************
+# Introduction
+# ************
 #
 # This manual describes the commands and events supported by the QEMU
 # storage daemon QMP.
@@ -51,7 +53,9 @@
 { 'include': '../../qapi/job.json' }
 
 ##
-# = Block devices
+# *************
+# Block devices
+# *************
 ##
 { 'include': '../../qapi/block-core.json' }
 { 'include': '../../qapi/block-export.json' }
tests/qapi-schema/doc-good.json +7 -3
index 14b808f9090..fac13425b72 100644
@@ -8,7 +8,9 @@
     'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } }
 
 ##
-# = Section
+# *******
+# Section
+# *******
 ##
 
 ##
@@ -16,7 +18,8 @@
 ##
 
 ##
-# == Subsection
+# Subsection
+# ==========
 #
 # *with emphasis*
 # @var {in braces}
@@ -144,7 +147,8 @@
   'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
 
 ##
-# == Another subsection
+# Another subsection
+# ==================
 ##
 
 ##
tests/qapi-schema/doc-good.out +7 -3
index dc8352eed4f..04a55072646 100644
@@ -55,13 +55,16 @@ event EVT_BOXED Object
     feature feat3
 doc freeform
     body=
-= Section
+*******
+Section
+*******
 doc freeform
     body=
 Just text, no heading.
 doc freeform
     body=
-== Subsection
+Subsection
+==========
 
 *with emphasis*
 @var {in braces}
@@ -155,7 +158,8 @@ description starts on the same line
 a feature
 doc freeform
     body=
-== Another subsection
+Another subsection
+==================
 doc symbol=cmd
     body=
 
Signature · 1 line
2.48.1
#10 lore raw

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

Quoted 3 lines · John Snow

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?

Quoted 4 lines

Tests and documentation are updated to match.

[...]

docs/devel/qapi-code-gen.rst structuring content.

Quoted 5 lines
docs/devel/qapi-code-gen.rst +0 -0
index 231cc0fecf7..dfdbeac5a5a 100644
@@ -876,25 +876,35 @@ structuring content.

Documentation comments
----------------------

A multi-line comment that starts and ends with a ``##`` line is a documentation comment.

If the documentation comment starts like ::

       ##
       # @SYMBOL:

it documents the definition of SYMBOL, else it's free-form documentation.

See below for more on Definition documentation_.

Free-form documentation may be used to provide additional text and structuring content.

docs/devel/qapi-code-gen.rst structuring content. · line 881

Quoted 8 lines
docs/devel/qapi-code-gen.rst +3 -2
 Headings and subheadings
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-A free-form documentation comment containing a line which starts with
-some ``=`` symbols and then a space defines a section heading::
+Free-form documentation does not start with ``@SYMBOL`` and can contain
+arbitrary rST markup. Headings can be marked up using the standard rST
+syntax::

Nothing stops you from using such markup in definition documentation. It's probably a bad idea, though.

I think it's easiest not to talk about the two kinds of doc blocks here at all. Scratch the first sentence?

Quoted 36 lines
docs/devel/qapi-code-gen.rst +16 -7
     ##
-    # = This is a top level heading
+    # *************************
+    # This is a level 2 heading
+    # *************************
     #
     # This is a free-form comment which will go under the
     # top level heading.
     ##
 
     ##
-    # == This is a second level heading
+    # This is a third level heading
+    # ==============================
+    #
+    # Level 4
+    # _______
+    #
+    # Level 5
+    # ^^^^^^^
+    #
+    # Level 6
+    # """""""
     ##
 
-A heading line must be the first line of the documentation
-comment block.
-
-Section headings must always be correctly nested, so you can only
-define a third-level heading inside a second-level heading, and so on.
+Level 1 headings are reserved for use by the generated documentation
+page itself, leaving level 2 as the highest level that should be used.
 
 
 Documentation markup

[...]

author
#11 lore raw

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

Quoted 53 lines · Markus Armbruster
Quoted 3 lines · John Snow

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?

Quoted 4 lines

Tests and documentation are updated to match.

[...]

docs/devel/qapi-code-gen.rst structuring content.

Quoted 5 lines
docs/devel/qapi-code-gen.rst +0 -0
index 231cc0fecf7..dfdbeac5a5a 100644
@@ -876,25 +876,35 @@ structuring content.

Documentation comments
----------------------

A multi-line comment that starts and ends with a ``##`` line is a documentation comment.

If the documentation comment starts like ::

       ##
       # @SYMBOL:

it documents the definition of SYMBOL, else it's free-form documentation.

See below for more on Definition documentation_.

Free-form documentation may be used to provide additional text and structuring content.

docs/devel/qapi-code-gen.rst structuring content. · line 881

Quoted 8 lines
docs/devel/qapi-code-gen.rst +3 -2
 Headings and subheadings
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-A free-form documentation comment containing a line which starts with
-some ``=`` symbols and then a space defines a section heading::
+Free-form documentation does not start with ``@SYMBOL`` and can contain
+arbitrary rST markup. Headings can be marked up using the standard rST
+syntax::

Nothing stops you from using such markup in definition documentation. It's probably a bad idea, though.

Quoted 3 lines

I think it's easiest not to talk about the two kinds of doc blocks here at all. Scratch the first sentence?

Sure.

Quoted 40 lines
Quoted 36 lines
docs/devel/qapi-code-gen.rst +16 -7
     ##
-    # = This is a top level heading
+    # *************************
+    # This is a level 2 heading
+    # *************************
     #
     # This is a free-form comment which will go under the
     # top level heading.
     ##
 
     ##
-    # == This is a second level heading
+    # This is a third level heading
+    # ==============================
+    #
+    # Level 4
+    # _______
+    #
+    # Level 5
+    # ^^^^^^^
+    #
+    # Level 6
+    # """""""
     ##
 
-A heading line must be the first line of the documentation
-comment block.
-
-Section headings must always be correctly nested, so you can only
-define a third-level heading inside a second-level heading, and so on.
+Level 1 headings are reserved for use by the generated documentation
+page itself, leaving level 2 as the highest level that should be used.
 
 
 Documentation markup

[...]

author
#12 lore raw

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

In reply to Markus Armbruster
Quoted 10 lines · Markus Armbruster
Quoted 3 lines · John Snow

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.

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.

Quoted 87 lines
Quoted 4 lines

Tests and documentation are updated to match.

[...]

docs/devel/qapi-code-gen.rst structuring content.

Quoted 5 lines
docs/devel/qapi-code-gen.rst +0 -0
index 231cc0fecf7..dfdbeac5a5a 100644
@@ -876,25 +876,35 @@ structuring content.

Documentation comments
----------------------

A multi-line comment that starts and ends with a ``##`` line is a documentation comment.

If the documentation comment starts like ::

       ##
       # @SYMBOL:

it documents the definition of SYMBOL, else it's free-form documentation.

See below for more on Definition documentation_.

Free-form documentation may be used to provide additional text and structuring content.

docs/devel/qapi-code-gen.rst structuring content. · line 881

Quoted 8 lines
docs/devel/qapi-code-gen.rst +3 -2
 Headings and subheadings
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-A free-form documentation comment containing a line which starts with
-some ``=`` symbols and then a space defines a section heading::
+Free-form documentation does not start with ``@SYMBOL`` and can contain
+arbitrary rST markup. Headings can be marked up using the standard rST
+syntax::

Nothing stops you from using such markup in definition documentation. It's probably a bad idea, though.

I think it's easiest not to talk about the two kinds of doc blocks here at all. Scratch the first sentence?

Quoted 36 lines
docs/devel/qapi-code-gen.rst +16 -7
     ##
-    # = This is a top level heading
+    # *************************
+    # This is a level 2 heading
+    # *************************
     #
     # This is a free-form comment which will go under the
     # top level heading.
     ##
 
     ##
-    # == This is a second level heading
+    # This is a third level heading
+    # ==============================
+    #
+    # Level 4
+    # _______
+    #
+    # Level 5
+    # ^^^^^^^
+    #
+    # Level 6
+    # """""""
     ##
 
-A heading line must be the first line of the documentation
-comment block.
-
-Section headings must always be correctly nested, so you can only
-define a third-level heading inside a second-level heading, and so on.
+Level 1 headings are reserved for use by the generated documentation
+page itself, leaving level 2 as the highest level that should be used.
 
 
 Documentation markup

[...]

#13 lore raw

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

Quoted 8 lines · John Snow
Quoted 6 lines · Markus Armbruster
Quoted 3 lines · John Snow

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.

Quoted 8 lines
Quoted 4 lines

"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

tests/qapi-schema/doc-good.json +3 -1
index 14b808f909..201462688f 100644
@@ -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:

tests/qapi-schema/doc-good.rst +1 -0
index 1e4c23305a..9978ac2e9c 100644
@@ -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:

tests/qapi-schema/doc-good.json +2 -1
index 14b808f909..201462688f 100644
@@ -165,7 +167,8 @@
 #
 # Returns: @Object
 #
-# Errors: some
+# Errors:
+#     some
 #
 # TODO: frobnicate
 #

The rST heading seems to work fine then.

The next-level heading

tests/qapi-schema/doc-good.json +2 -1
index 14b808f9090..fac13425b72 100644
@@ -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.

Quoted 3 lines

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.

[...]

#14 lore raw

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

Quoted 18 lines · Markus Armbruster
Quoted 16 lines · John Snow
Quoted 10 lines · Markus Armbruster
Quoted 3 lines · John Snow

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.

[...]

Quoted 11 lines

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.

Quoted 3 lines

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.

[...]

I'm going with

docs/sphinx: remove special parsing for freeform sections

Remove the QAPI doc section heading syntax, use plain rST section headings instead.

Tests and documentation are updated to match.

Interestingly, Plain rST headings work fine before this patch, except for over- and underlining with '=', which the doc parser rejected as invalid QAPI doc section heading in free-form comments.

author
#15 lore raw

PATCH v3 5/5 qapi: lift restriction on using '=' in doc blocks

In reply to John Snow
---
 scripts/qapi/parser.py                 |  4 ----
 tests/qapi-schema/doc-bad-section.err  |  1 -
 tests/qapi-schema/doc-bad-section.json | 10 ----------
 tests/qapi-schema/doc-bad-section.out  |  0
 tests/qapi-schema/meson.build          |  1 -
 5 files changed, 16 deletions(-)
 delete mode 100644 tests/qapi-schema/doc-bad-section.err
 delete mode 100644 tests/qapi-schema/doc-bad-section.json
 delete mode 100644 tests/qapi-schema/doc-bad-section.out
scripts/qapi/parser.py +0 -4
index aad7e249f86..d43a123cd74 100644
@@ -584,10 +584,6 @@ def get_doc(self) -> 'QAPIDoc':
                         doc.append_line(text)
                     line = self.get_doc_indented(doc)
                     no_more_args = True
-                elif line.startswith('='):
-                    raise QAPIParseError(
-                        self,
-                        "unexpected '=' markup in definition documentation")
                 else:
                     # plain paragraph
                     doc.ensure_untagged_section(self.info)
tests/qapi-schema/doc-bad-section.err deleted +0 -1
deleted file mode 100644
index 785cacc08c4..00000000000
@@ -1 +0,0 @@
-doc-bad-section.json:5:1: unexpected '=' markup in definition documentation
tests/qapi-schema/doc-bad-section.json deleted +0 -10
deleted file mode 100644
index 8175d95867e..00000000000
@@ -1,10 +0,0 @@
-# = section within an expression comment
-
-##
-# @Enum:
-# == No good here
-# @one: The _one_ {and only}
-#
-# @two is undocumented
-##
-{ 'enum': 'Enum', 'data': [ 'one', 'two' ] }
tests/qapi-schema/doc-bad-section.out deleted +0 -0
deleted file mode 100644
index e69de29bb2d..00000000000
tests/qapi-schema/meson.build +0 -1
index 9577178b6ff..c47025d16d8 100644
@@ -61,7 +61,6 @@ schemas = [
   'doc-bad-event-arg.json',
   'doc-bad-feature.json',
   'doc-bad-indent.json',
-  'doc-bad-section.json',
   'doc-bad-symbol.json',
   'doc-bad-union-member.json',
   'doc-before-include.json',
Signature · 1 line
2.48.1
#16 lore raw

Re: [PATCH v3 5/5] qapi: lift restriction on using '=' in doc blocks

John Snow <[email protected]> writes:

Let's explain why. Here's my attempt:

We reject lines starting with '=' in definition documentation. This made sense when such lines were headings in free-form documentation, but not in definition documentation.

Before the previous commit, lines starting with '=' were headings in free-form documentation, and rejected in definition documentation, where such headings could not work.

The previous commit dropped the headings feature from free-form documentation, because we can simply use plain rST headings. Rejecting them in definition documentation no longer makes sense, so drop that, too.

Quoted 1 line
Acked-by Reviewed-by on the v3 series Applied
#17 lore raw
In reply to John Snow
Quoted 4 lines · John Snow

Remove docs/sphinx/qapidoc_legacy.py, and remove special parsing of freeform QAPI documentation block sections in favor of using standard rST syntax that is included in the final document with no special parsing or post-processing.

PATCH 1-3

PATCH 4+5

Queued, thanks!