mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments

Browse Source 
When a command's arguments are specified as an explicit type T,
generated documentation points to the members of T.

Example:

    ##
    # @announce-self:
    #
    # Trigger generation of broadcast RARP frames to update network
    [...]
    ##
    { 'command': 'announce-self', 'boxed': true,
      'data' : 'AnnounceParameters'}

generates

    "announce-self" (Command)
    -------------------------

    Trigger generation of broadcast RARP frames to update network
    [...]

    Arguments
    ~~~~~~~~~

    The members of "AnnounceParameters"

Except when the command takes its arguments unboxed , i.e. it doesn't
have 'boxed': true, we generate *nothing*.  A few commands have a
reference in their doc comment to compensate, but most don't.

Example:

    ##
    # @blockdev-snapshot-sync:
    #
    # Takes a synchronous snapshot of a block device.
    #
    # For the arguments, see the documentation of BlockdevSnapshotSync.
    [...]
    ##
    { 'command': 'blockdev-snapshot-sync',
      'data': 'BlockdevSnapshotSync',
      'allow-preconfig': true }

generates

    "blockdev-snapshot-sync" (Command)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Takes a synchronous snapshot of a block device.

    For the arguments, see the documentation of BlockdevSnapshotSync.
    [...]

Same for event data.

Fix qapidoc.py to generate the reference regardless of boxing.  Delete
now redundant references in the doc comments.

Fixes: 4078ee5469 (docs/sphinx: Add new qapi-doc Sphinx extension)
Cc: qemu-stable@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240628112756.794237-1-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
(cherry picked from commit e389929d19)
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
This commit is contained in:
Markus Armbruster 2024-06-28 13:27:56 +02:00 committed by Michael Tokarev
parent 837864aa6c
commit e4a9b44f7a
2 changed files with 5 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/sphinx/qapidoc.py
View File

@ -219,15 +219,15 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
section += dlnode
return [section]
def _nodes_for_arguments(self, doc, boxed_arg_type):
def _nodes_for_arguments(self, doc, arg_type):
"""Return list of doctree nodes for the arguments section"""
if boxed_arg_type:
if arg_type and not arg_type.is_implicit():
assert not doc.args
section = self._make_section('Arguments')
dlnode = nodes.definition_list()
dlnode += self._make_dlitem(
[nodes.Text('The members of '),
nodes.literal('', boxed_arg_type.name)],
nodes.literal('', arg_type.name)],
None)
section += dlnode
return [section]
@ -331,8 +331,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
allow_preconfig, coroutine):
doc = self._cur_doc
self._add_doc('Command',
self._nodes_for_arguments(doc,
arg_type if boxed else None)
self._nodes_for_arguments(doc, arg_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
@ -340,8 +339,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
def visit_event(self, name, info, ifcond, features, arg_type, boxed):
doc = self._cur_doc
self._add_doc('Event',
self._nodes_for_arguments(doc,
arg_type if boxed else None)
self._nodes_for_arguments(doc, arg_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))

7
qapi/block-core.json
View File

@ -1671,8 +1671,6 @@
#
# Takes a synchronous snapshot of a block device.
#
# For the arguments, see the documentation of BlockdevSnapshotSync.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
@ -1701,8 +1699,6 @@
# device, the block device changes to using 'overlay' as its new
# active image.
#
# For the arguments, see the documentation of BlockdevSnapshot.
#
# Features:
#
# @allow-write-only-overlay: If present, the check whether this
@ -6061,9 +6057,6 @@
# string, or a snapshot with name already exists, the operation will
# fail.
#
# For the arguments, see the documentation of
# BlockdevSnapshotInternal.
#
# Errors:
# - If @device is not a valid block device, GenericError
# - If any snapshot matching @name exists, or @name is empty,