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