docs: remove legacy qapidoc
cover docs: remove legacy qapidoc
This series is RFC-ish and based on python-qapi-linting-v4, which I think ... should show up in origin/master soon(?).
John Snow (3):
docs: fix errors formatting in test-good
docs: remove legacy QAPI manual generator
docs: remove special parsing for freeform sections
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 | 62 +-- 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 | 7 - storage-daemon/qapi/qapi-schema.json | 8 +- tests/qapi-schema/doc-good.json | 13 +- 52 files changed, 170 insertions(+), 572 deletions(-) delete mode 100644 docs/sphinx/qapidoc_legacy.py
Signature · 1 line
2.48.1
PATCH 1/3 docs: fix errors formatting in test-good
If we remove the legacy parser, this formulation begins to fail because the body text is appended directly after the field list entry, which is invalid rST syntax.
Markus: suggest where the new Exception(s) should go, if anywhere, and how to update the tests? I'm assuming deeply you'll want to.
--- tests/qapi-schema/doc-good.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
tests/qapi-schema/doc-good.json +2 -1
@@ -165,7 +165,8 @@ # # Returns: @Object # -# Errors: some +# Errors: +# - some # # TODO: frobnicate #
Signature · 1 line
2.48.1
Re: [PATCH 1/3] docs: fix errors formatting in test-good
Quoted 6 lines · John Snow
If we remove the legacy parser, this formulation begins to fail because the body text is appended directly after the field list entry, which is invalid rST syntax.
Markus: suggest where the new Exception(s) should go, if anywhere, and how to update the tests? I'm assuming deeply you'll want to.
I'm confused and out of time for the week. Can you give me a bit more context?
Quoted 19 lines
Signed-off-by John Snow <[email protected]>--- tests/qapi-schema/doc-good.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)tests/qapi-schema/doc-good.json +2
-1@@ -165,7 +165,8 @@ # # Returns: @Object # -# Errors: some +# Errors: +# - some # # TODO: frobnicate #
PATCH 2/3 docs: 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 has the side effect of converting the tests to use the new system, too.
--- 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 +- 6 files changed, 2 insertions(+), 468 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 (
@@ -504,15 +502,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()
@@ -590,21 +582,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)
@@ -617,11 +598,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
@@ -1,6 +1,6 @@ #!/bin/sh -e 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
Signature · 1 line
2.48.1
Re: [PATCH 2/3] docs: remove legacy QAPI manual generator
Quoted 15 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 has the side effect of converting the tests to use the new system, too.
Signed-off-by John Snow <[email protected]>--- 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 +- 6 files changed, 2 insertions(+), 468 deletions(-)
Quoted 1 line
delete mode 100644
docs/sphinx/qapidoc_legacy.py
PATCH 3/3 docs: 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.
Markus: presumably you'll want to update the tests and/or change the parser errors. Please advise!
--- 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 +++++--- 47 files changed, 166 insertions(+), 103 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
@@ -391,44 +391,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 = 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(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 +# ================== ## ##
Signature · 1 line
2.48.1
Quoted 2 lines · John Snow
This series is RFC-ish and based on python-qapi-linting-v4, which I think ... should show up in origin/master soon(?).
Please use
Based-on: <message-id>
Out of time for today, or I'd hunt for the exact base myself.