sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
PATCH 1/1 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.
--- docs/sphinx/qapidoc.py | 12 +++++------- qapi/block-core.json | 7 ------- 2 files changed, 5 insertions(+), 14 deletions(-)
docs/sphinx/qapidoc.py +5 -7
@@ -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]
@@ -332,8 +332,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))
@@ -341,8 +340,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))
qapi/block-core.json +0 -7
@@ -1675,8 +1675,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 #
@@ -1705,8 +1703,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
@@ -6065,9 +6061,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,
Signature · 1 line
2.45.0
Quoted 55 lines · Markus Armbruster
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. [...]
Quoted 9 lines
Same for event data.
Fix
qapidoc.pyto generate the reference regardless of boxing. Delete now redundant references in the doc comments.Fixes 4078ee5469e5 (docs/sphinx: Add new qapi-doc Sphinx extension)Signed-off-by Markus Armbruster <[email protected]>
LGTM
Didn't test because my branch is a mess at the moment but I don't see anything obviously wrong.
If it breaks something I'm sure I'll find out, so
---
Quoted 87 lines
docs/sphinx/qapidoc.py | 12 +++++------- qapi/block-core.json | 7 ------- 2 files changed, 5 insertions(+), 14 deletions(-)docs/sphinx/qapidoc.py +4
-5@@ -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]@@ -332,8 +332,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))docs/sphinx/qapidoc.py +1
-2@@ -341,8 +340,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))qapi/block-core.json +0
-8@@ -1675,8 +1675,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 #@@ -1705,8 +1703,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@@ -6065,9 +6061,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.45.0