On Wed, Jun 26, 2024, 1:18 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes:
>
> > Eliminate the "Example" sections in QAPI doc blocks, converting them
> > into QMP example code blocks. This is generally done in this patch by
> > converting "Example:" or "Examples:" lines into ".. code-block:: QMP"
> > lines.
>
> [...]
>
> > diff --git a/qapi/migration.json b/qapi/migration.json
> > index 85a14bb4308..849358b6387 100644
> > --- a/qapi/migration.json
> > +++ b/qapi/migration.json
>
> [...]
>
> > @@ -336,7 +338,35 @@
> > # }
> > # }
> > #
> > -# 5. Migration is being performed and XBZRLE is active:
> > +# .. code-block:: QMP
> > +# :caption: Example: Migration is being performed and XBZRLE is
> active
> > +#
> > +# -> { "execute": "query-migrate" }
> > +# <- {
> > +# "return":{
> > +# "status":"active",
> > +# "total-time":12345,
> > +# "setup-time":12345,
> > +# "expected-downtime":12345,
> > +# "ram":{
> > +# "total":1057024,
> > +# "remaining":1053304,
> > +# "transferred":3720,
> > +# "duplicate":123,
> > +# "normal":123,
> > +# "normal-bytes":123456,
> > +# "dirty-sync-count":15
> > +# },
> > +# "disk":{
> > +# "total":20971520,
> > +# "remaining":20880384,
> > +# "transferred":91136
> > +# }
> > +# }
> > +# }
> > +#
> > +# .. code-block:: QMP
> > +# :caption: Example: Migration is being performed and XBZRLE is
> active
> > #
> > # -> { "execute": "query-migrate" }
> > # <- {
>
> Example accidentally duplicated.
>
Fixed this yesterday, oopsie. I think this was a rebase goof.
>
> [...]
>
> > diff --git a/tests/qapi-schema/doc-good.json
> b/tests/qapi-schema/doc-good.json
> > index 4b338cc0186..2774a7ce14d 100644
> > --- a/tests/qapi-schema/doc-good.json
> > +++ b/tests/qapi-schema/doc-good.json
> > @@ -46,11 +46,13 @@
> > #
> > # Duis aute irure dolor
> > #
> > -# Example:
> > +# .. code-block:: QMP
> > +# :caption: Example:
>
> See [*] below.
>
> > #
> > # -> in
> > # <- out
> > -# Examples:
> > +# .. code-block::
> > +#
>
> Likewise.
>
> > # - *verbatim*
> > # - {braces}
> > ##
> > @@ -172,12 +174,13 @@
> > #
> > # Duis aute irure dolor
> > #
> > -# Example:
> > +# .. code-block::
> > #
> > # -> in
> > # <- out
> > #
> > -# Examples:
> > +# .. code-block::
> > +#
> > # - *verbatim*
> > # - {braces}
> > #
> > @@ -196,7 +199,7 @@
> > # @cmd-feat1: a feature
> > # @cmd-feat2: another feature
> > #
> > -# Example:
> > +# .. code-block::
> > #
> > # -> in
> > #
> > diff --git a/tests/qapi-schema/doc-good.out
> b/tests/qapi-schema/doc-good.out
> > index 2c9b4e419cb..347b9cb7134 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -93,11 +93,13 @@ Notes:
> >
> > Duis aute irure dolor
> >
> > -Example:
> > +.. code-block:: QMP
> > + :caption: Example:
>
> [*] This demonstrates the "Example: ..." is *not* recognized as a
> "Example" section before the patch (compare to the change we get for
> recognized sections below).
>
> I pointed out the same issue for "Note" in review of PATCH 9, and
> suggested ways to resolve it. Pick a way there, and use it here as well
>
ACK
> >
> > -> in
> > <- out
> > -Examples:
> > +.. code-block::
> > +
> > - *verbatim*
> > - {braces}
> > doc symbol=Enum
> > @@ -184,10 +186,14 @@ frobnicate
> > - Ut enim ad minim veniam
> >
> > Duis aute irure dolor
> > - section=Example
> > +
> > +.. code-block::
> > +
> > -> in
> > <- out
> > - section=Examples
> > +
> > +.. code-block::
> > +
> > - *verbatim*
> > - {braces}
> > section=Since
> > @@ -199,7 +205,9 @@ If you're bored enough to read this, go see a video
> of boxed cats
> > a feature
> > feature=cmd-feat2
> > another feature
> > - section=Example
> > + section=None
> > +.. code-block::
> > +
> > -> in
> >
> > <- out
> > diff --git a/tests/qapi-schema/doc-good.txt
> b/tests/qapi-schema/doc-good.txt
> > index b89f35d5476..1bd31f0938d 100644
> > --- a/tests/qapi-schema/doc-good.txt
> > +++ b/tests/qapi-schema/doc-good.txt
> > @@ -35,7 +35,10 @@ Duis aute irure dolor
> >
> > Example:
> >
> > --> in <- out Examples: - *verbatim* - {braces}
> > +-> in <- out .. code-block:
>
> Looks like Sphinx didn't recognize the .. code-block: directive.
> Generator bug?
>
Honestly, not sure. Depends on what generates the plaintext...
... on IRC just now you say it's a Sphinx builder. I'll investigate why
this happens before resending.
> > +
> > + - *verbatim*
> > + - {braces}
> >
> >
> > "Enum" (Enum)
> > @@ -219,17 +222,9 @@ Notes:
> >
> > Duis aute irure dolor
> >
> > -
> > -Example
> > -~~~~~~~
> > -
> > -> in
> > <- out
> >
> > -
> > -Examples
> > -~~~~~~~~
> > -
> > - *verbatim*
> > - {braces}
> >
> > @@ -260,10 +255,6 @@ Features
> > "cmd-feat2"
> > another feature
> >
> > -
> > -Example
> > -~~~~~~~
> > -
> > -> in
> >
> > <- out
>
> Rendering to text now loses the "Example" heading.
>
> We render to manual pages in addition to HTML. Looks like we don't lose
> "Example" there. Odd.
>
> We render to text only for diffing purposes. The loss there could
> perhaps be tolerated. Still, could you avoid it with reasonable effort?
>
I've rewritten how Examples are handled; I'll check to see how they render
to plaintext and see what can be done.
>
