aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2024-06-28 13:27:56 +0200
committerMarkus Armbruster <armbru@redhat.com>2024-07-06 08:58:24 +0200
commite389929d19a543ea5b34d02553b355f9f1c03162 (patch)
tree96e50b2eb03d6fcfe07518a525d63d895ec6bc3a /docs
parent65fa48c79f20a37c7204f9e43dd7cc3058aa066c (diff)
downloadqemu-e389929d19a543ea5b34d02553b355f9f1c03162.zip
qemu-e389929d19a543ea5b34d02553b355f9f1c03162.tar.gz
qemu-e389929d19a543ea5b34d02553b355f9f1c03162.tar.bz2
sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
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>
Diffstat (limited to 'docs')
-rw-r--r--docs/sphinx/qapidoc.py12
1 files changed, 5 insertions, 7 deletions
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index efcd846..2b06750 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -230,15 +230,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]
@@ -352,8 +352,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))
@@ -361,8 +360,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))