[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Stable-9.0.2 26/27] sphinx/qapidoc: Fix to generate doc for explicit, u
From: |
Michael Tokarev |
Subject: |
[Stable-9.0.2 26/27] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments |
Date: |
Mon, 15 Jul 2024 12:34:33 +0300 |
From: Markus Armbruster <armbru@redhat.com>
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: 4078ee5469e5 (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 e389929d19a543ea5b34d02553b355f9f1c03162)
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8d428c64b0..8d3518e887 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -219,15 +219,15 @@ def _nodes_for_enum_values(self, doc):
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 @@ def visit_command(self, name, info, ifcond, features,
arg_type,
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 @@ def visit_command(self, name, info, ifcond, features,
arg_type,
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))
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 746d1694c2..4b18e01b85 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -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,
--
2.39.2
- [Stable-9.0.2 00/27] Patch Round-up for stable 9.0.2, frozen on 2024-07-14, Michael Tokarev, 2024/07/15
- [Stable-9.0.2 23/27] virtio-pci: Fix the failure process in kvm_virtio_pci_vector_use_one(), Michael Tokarev, 2024/07/15
- [Stable-9.0.2 25/27] char-stdio: Restore blocking mode of stdout on exit, Michael Tokarev, 2024/07/15
- [Stable-9.0.2 27/27] hw/nvme: fix number of PIDs for FDP RUH update, Michael Tokarev, 2024/07/15
- [Stable-9.0.2 26/27] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments,
Michael Tokarev <=
- [Stable-9.0.2 24/27] virtio: remove virtio_tswap16s() call in vring_packed_event_read(), Michael Tokarev, 2024/07/15