1. Patchew
  2. QEMU
  3. View series

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

Markus Armbruster posted 1 patch 2 months, 1 week ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20240628112756.794237-1-armbru@redhat.com
Maintainers: Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, Peter Maydell <peter.maydell@linaro.org>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Eric Blake <eblake@redhat.com>
docs/sphinx/qapidoc.py | 12 +++++-------
qapi/block-core.json   |  7 -------
2 files changed, 5 insertions(+), 14 deletions(-)
[PATCH] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
Posted by Markus Armbruster 2 months, 1 week ago 
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>
---
 docs/sphinx/qapidoc.py | 12 +++++-------
 qapi/block-core.json   |  7 -------
 2 files changed, 5 insertions(+), 14 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index f270b494f0..aacb2cd721 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]
@@ -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))
diff --git a/qapi/block-core.json b/qapi/block-core.json
index df5e07debd..c5cb0c5d56 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -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
Re: [PATCH] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
Posted by John Snow 2 months, 1 week ago 
On Fri, Jun 28, 2024, 7:28 AM Markus Armbruster <armbru@redhat.com> wrote:

> 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>
>

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

Reviewed-by: John Snow <jsnow@redhat.com>


---
>  docs/sphinx/qapidoc.py | 12 +++++-------
>  qapi/block-core.json   |  7 -------
>  2 files changed, 5 insertions(+), 14 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index f270b494f0..aacb2cd721 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]
> @@ -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))
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index df5e07debd..c5cb0c5d56 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -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
>
>

Patchew 2.1-devel-b67e4c2

© 2016 - 2024 Red Hat, Inc.