| Message ID | 20240628112756.794237-1-armbru@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments | expand |
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 > >
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,
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(-)