Re: [PATCH 7/8] qapi: convert "Example" sections with longer prose

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3934 bytes --]

On Tue, Jul 9, 2024 at 7:35 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > These examples require longer explanations or have explanations that
> > require markup to look reasonable when rendered and so use the longer
> > form of the ".. qmp-example::" directive.
> >
> > By using the :annotated: option, the content in the example block is
> > assumed *not* to be a code block literal and is instead parsed as normal
> > rST - with the exception that any code literal blocks after `::` will
> > assumed to be a QMP code literal block.
> >
> > Note: There's one title-less conversion in this patch that comes along
> > for the ride because it's part of a larger "Examples" block that was
> > better to convert all at once.
> >
> > See commit-5: "docs/qapidoc: create qmp-example directive", for a
> >               detailed explanation of this custom directive syntax.
> >
> > See commit+1: "qapi: remove "Example" doc section" for a detailed
> >               explanation of why.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  qapi/block.json     | 26 ++++++++++++++++----------
> >  qapi/machine.json   | 30 ++++++++++++++++++++----------
> >  qapi/migration.json |  7 +++++--
> >  qapi/virtio.json    | 24 ++++++++++++++++++------
> >  4 files changed, 59 insertions(+), 28 deletions(-)
> >
> > diff --git a/qapi/block.json b/qapi/block.json
> > index 5ddd061e964..d95e9fd8140 100644
> > --- a/qapi/block.json
> > +++ b/qapi/block.json
> > @@ -545,31 +545,37 @@
> >  #
> >  # Since: 4.0
> >  #
> > -# Example:
> > +# .. qmp-example::
> > +#    :annotated:
> >  #
> > -#     Set new histograms for all io types with intervals
> > -#     [0, 10), [10, 50), [50, 100), [100, +inf):
> > +#    Set new histograms for all io types with intervals
> > +#    [0, 10), [10, 50), [50, 100), [100, +inf)::
> >  #
> >  #     -> { "execute": "block-latency-histogram-set",
> >  #          "arguments": { "id": "drive0",
> >  #                         "boundaries": [10, 50, 100] } }
> >  #     <- { "return": {} }
> >  #
> > -# Example:
> > +# .. qmp-example::
> > +#    :annotated:
> >  #
> > -#     Set new histogram only for write, other histograms will remain
> > -#     not changed (or not created):
> > +#    Set new histogram only for write, other histograms will remain
> > +#    not changed (or not created)::
> >  #
> >  #     -> { "execute": "block-latency-histogram-set",
> >  #          "arguments": { "id": "drive0",
> >  #                         "boundaries-write": [10, 50, 100] } }
> >  #     <- { "return": {} }
> >  #
> > -# Example:
> > +# .. qmp-example::
> > +#    :annotated:
> >  #
> > -#     Set new histograms with the following intervals:
> > -#       read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
> > -#       write: [0, 1000), [1000, 5000), [5000, +inf)
> > +#    Set new histograms with the following intervals:
> > +#
> > +#    - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
> > +#    - write: [0, 1000), [1000, 5000), [5000, +inf)
> > +#
> > +#    ::
> >  #
> >  #     -> { "execute": "block-latency-histogram-set",
> >  #          "arguments": { "id": "drive0",
>    #                         "boundaries": [10, 50, 100],
>    #                         "boundaries-write": [1000, 5000] } }
>    #     <- { "return": {} }
>    #
>    # .. qmp-example::
>    #    :title: Remove all latency histograms
>    #
>    #     -> { "execute": "block-latency-histogram-set",
>    #          "arguments": { "id": "drive0" } }
>    #     <- { "return": {} }
>    ##
>
> I think using :annotated: for this one as well will look better.
>

Sure, why not. I tried to minimize more complex rewrites as a rule, but
it's no problem to change the styling to taste.


>
> [...]
>
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>
>

[-- Attachment #2: Type: text/html, Size: 5600 bytes --]