Re: [PATCH 13/13] qapi: convert "Example" sections to rST

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@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.


[...]

> 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

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

> +
> +   - *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?