On Mon, Jul 15, 2024, 5:34 AM Michael Tokarev <m...@tls.msk.ru> wrote:
> From: Markus Armbruster <arm...@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-sta...@nongnu.org
> Signed-off-by: Markus Armbruster <arm...@redhat.com>
> Message-ID: <20240628112756.794237-1-arm...@redhat.com>
> Reviewed-by: John Snow <js...@redhat.com>
> (cherry picked from commit e389929d19a543ea5b34d02553b355f9f1c03162)
> Signed-off-by: Michael Tokarev <m...@tls.msk.ru>
>
Just do me a favor and test build the html docs in the stable branch and
verify that they appear to render correctly with a quick visual glance --
we've been poking around a lot in that area.
I don't see any obvious point of conflict in this patch, but I have a
nagging doubt.
As long as they build and they look alright, I'm confident it's fine.
> 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
>
>
