docs: remove legacy qapidoc
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
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
@@ -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
Re: [PATCH v3 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections
Quoted 1 line · John Snow
Signed-off-by John Snow <[email protected]>
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@@ -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: """
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
Signed-off-by John Snow <[email protected]>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
PATCH v3 2/5 docs/sphinx: parse @references in freeform text
In reply to John SnowOversight 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
@@ -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
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:-)
Signed-off-by John Snow <[email protected]>--- docs/sphinx/qapidoc.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)docs/sphinx/qapidoc.py +0
-0
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):
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:-)
Signed-off-by John Snow <[email protected]>--- docs/sphinx/qapidoc.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-)docs/sphinx/qapidoc.py +0
-0@@ -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):
PATCH v3 3/5 docs/sphinx: remove legacy QAPI manual generator
In reply to John SnowThanks 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
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
Quoted 1 line
Signed-off-by John Snow <[email protected]>
PATCH v3 4/5 docs/sphinx: remove special parsing for freeform sections
In reply to John SnowThis 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
@@ -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
@@ -11,7 +11,9 @@ # later. See the COPYING file in the top-level directory. ## -# = Firmware +# ******** +# Firmware +# ******** ## { 'pragma': {
docs/interop/vhost-user.json +3 -1
@@ -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
@@ -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
@@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = ACPI +# **** +# ACPI +# **** ## ##
qapi/audio.json +3 -1
@@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Audio +# ***** +# Audio +# ***** ## ##
qapi/authz.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = User authorization +# ****************** +# User authorization +# ****************** ## ##
qapi/block-core.json +2 -1
@@ -2,7 +2,8 @@ # vim: filetype=python ## -# == Block core (VM unrelated) +# Block core (VM unrelated) +# ========================= ## { 'include': 'common.json' }
qapi/block-export.json +2 -1
@@ -2,7 +2,8 @@ # vim: filetype=python ## -# == Block device exports +# Block device exports +# ==================== ## { 'include': 'sockets.json' }
qapi/block.json +5 -2
@@ -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
@@ -3,7 +3,9 @@ # ## -# = Character devices +# ***************** +# Character devices +# ***************** ## { 'include': 'sockets.json' }
qapi/common.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Common data types +# ***************** +# Common data types +# ***************** ## ##
qapi/compat.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Compatibility policy +# ******************** +# Compatibility policy +# ******************** ## ##
qapi/control.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = QMP monitor control +# ******************* +# QMP monitor control +# ******************* ## ##
qapi/crypto.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Cryptography +# ************ +# Cryptography +# ************ ## ##
qapi/cryptodev.json +3 -1
@@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Cryptography devices +# ******************** +# Cryptography devices +# ******************** ## ##
qapi/cxl.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = CXL devices +# *********** +# CXL devices +# *********** ## ##
qapi/dump.json +3 -1
@@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Dump guest memory +# ***************** +# Dump guest memory +# ***************** ## ##
qapi/ebpf.json +3 -1
@@ -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
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = QMP errors +# ********** +# QMP errors +# ********** ## ##
qapi/introspect.json +3 -1
@@ -10,7 +10,9 @@ # See the COPYING file in the top-level directory. ## -# = QMP introspection +# ***************** +# QMP introspection +# ***************** ## ##
qapi/job.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Background jobs +# *************** +# Background jobs +# *************** ## ##
qapi/machine-common.json +3 -1
@@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Common machine types +# ******************** +# Common machine types +# ******************** ## ##
qapi/machine.json +3 -1
@@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Machines +# ******** +# Machines +# ******** ## { 'include': 'common.json' }
qapi/migration.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Migration +# ********* +# Migration +# ********* ## { 'include': 'common.json' }
qapi/misc.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Miscellanea +# *********** +# Miscellanea +# *********** ## { 'include': 'common.json' }
qapi/net.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Net devices +# *********** +# Net devices +# *********** ## { 'include': 'sockets.json' }
qapi/pci.json +3 -1
@@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = PCI +# *** +# PCI +# *** ## ##
qapi/qapi-schema.json +3 -1
@@ -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
@@ -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
@@ -10,7 +10,9 @@ { 'include': 'crypto.json' } ## -# = QEMU Object Model (QOM) +# *********************** +# QEMU Object Model (QOM) +# *********************** ## ##
qapi/replay.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Record/replay +# ************* +# Record/replay +# ************* ## { 'include': 'common.json' }
qapi/rocker.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Rocker switch device +# ******************** +# Rocker switch device +# ******************** ## ##
qapi/run-state.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = VM run state +# ************ +# VM run state +# ************ ## ##
qapi/sockets.json +3 -1
@@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Socket data types +# ***************** +# Socket data types +# ***************** ## ##
qapi/stats.json +3 -1
@@ -9,7 +9,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = Statistics +# ********** +# Statistics +# ********** ## ##
qapi/tpm.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = TPM (trusted platform module) devices +# ************************************* +# TPM (trusted platform module) devices +# ************************************* ## ##
qapi/trace.json +3 -1
@@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Tracing +# ******* +# Tracing +# ******* ## ##
qapi/transaction.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Transactions +# ************ +# Transactions +# ************ ## { 'include': 'block-core.json' }
qapi/uefi.json +3 -1
@@ -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
@@ -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
@@ -3,7 +3,9 @@ # ## -# = VFIO devices +# ************ +# VFIO devices +# ************ ## ##
qapi/virtio.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Virtio devices +# ************** +# Virtio devices +# ************** ## ##
qapi/yank.json +3 -1
@@ -3,7 +3,9 @@ # ## -# = Yank feature +# ************ +# Yank feature +# ************ ## ##
scripts/qapi/parser.py +0 -7
@@ -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
@@ -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
@@ -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
@@ -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
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.
Signed-off-by John Snow <[email protected]>
[...]
docs/devel/qapi-code-gen.rst structuring content.
Quoted 5 lines
docs/devel/qapi-code-gen.rst +0
-0@@ -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
-2Headings 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
[...]
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.
Signed-off-by John Snow <[email protected]>[...]
docs/devel/qapi-code-gen.rst structuring content.
Quoted 5 lines
docs/devel/qapi-code-gen.rst +0
-0@@ -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
-2Headings 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[...]
Re: [PATCH v3 4/5] docs/sphinx: remove special parsing for freeform sections
In reply to Markus ArmbrusterQuoted 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.
Signed-off-by John Snow <[email protected]>[...]
docs/devel/qapi-code-gen.rst structuring content.
Quoted 5 lines
docs/devel/qapi-code-gen.rst +0
-0@@ -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
-2Headings 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[...]
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
@@ -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
@@ -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
@@ -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
@@ -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.
[...]
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.
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
@@ -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
@@ -1 +0,0 @@ -doc-bad-section.json:5:1: unexpected '=' markup in definition documentation
tests/qapi-schema/doc-bad-section.json deleted +0 -10
@@ -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
tests/qapi-schema/meson.build +0 -1
@@ -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
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
Signed-off-by John Snow <[email protected]>
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!