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.
>
> The old "Example:" or "Examples:" syntax is now caught as an error; but
> with the previous commit, "Example::" is still permitted as explicit rST
> syntax. ('Example' is not special in this case; any sentence that ends
> with "::" will start an indented code block in rST.)
>
> The ".. code-block:: QMP" form explicitly applies the QMP lexer and will
> loosely validate an example as valid QMP/JSON. The "::" form does not
> apply any lexer in particular and will not emit any errors.
>
> It is possible to choose the QMP lexer with the "::" form by using the
> Sphinx directive ".. highlight:: QMP" in the document above where the
> example appears; but this changes the lexer for *all* subsequent "::"
> style code-blocks in the document thereafter.
>
> This patch does not change the default lexer for the legacy qapidoc
> generator documents; future patches for the new qapidoc generator *may*
> change this default.
>
> This patch has several benefits:
>
> 1. Example sections can now be written more arbitrarily, mixing
> explanatory paragraphs and code blocks however desired.
>
> 2. "Example sections" can now use fully arbitrary rST.
Do the double-quotes signify something I'm missing?
They aren't *sections* (QAPIDoc terminology) anymore, but was at a loss for more precise phrasing.
>
> 3. All code blocks are now lexed and validated as QMP; increasing
> usability of the docs and ensuring validity of example snippets.
>
> (To some extent - This patch only gaurantees it lexes correctly, not
> that it's valid under the JSON or QMP grammars. It will catch most
> small mistakes, however.)
>
> 4. Each code-block can be captioned independently without bypassing the
> QMP lexer/validator.
>
> (i.e. code blocks are now for *code* only, so we don't have to
> sacrifice annotations/captions for having lexicographically correct
> examples.)
>
> For any sections with more than one example, examples are split up into
> multiple code-block regions. If annotations are present, those
> annotations are converted into code-block captions instead, e.g.
>
> ```
> Examples:
>
> 1. Lorem Ipsum
>
> -> { "foo": "bar" }
> ```
>
> Is rewritten as:
>
> ```
> .. code-block:: QMP
> :caption: Example: Lorem Ipsum
>
> -> { "foo": "bar" }
> ```
>
> This process was only semi-automated:
>
> 1. Replace "Examples?:" sections with sed:
>
> sed -i 's|# Example:|# .. code-block:: QMP|' *.json
> sed -i 's|# Examples:|# .. code-block:: QMP|' *.json
>
> 2. Identify sections that no longer parse successfully by attempting the
> doc build, convert annotations into captions manually.
> (Tedious, oh well.)
>
> 3. Add captions where still needed:
>
> sed -zi 's|# .. code-block:: QMP\n#\n|# .. code-block:: QMP\n# :caption: Example\n#\n|g' *.json
>
> Not fully ideal, but hopefully not something that has to be done very
> often. (Or ever again.)
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
[...]
> diff --git a/qapi/pci.json b/qapi/pci.json
> index f51159a2c4c..9192212661b 100644
> --- a/qapi/pci.json
> +++ b/qapi/pci.json
> @@ -182,7 +182,8 @@
> #
> # Since: 0.14
> #
> -# Example:
> +# .. code-block:: QMP
> +# :caption: Example
> #
> # -> { "execute": "query-pci" }
> # <- { "return": [
> @@ -311,8 +312,7 @@
> # ]
> # }
> #
> -# Note: This example has been shortened as the real response is too
> -# long.
> +# This example has been shortened as the real response is too long.
Squash into PATCH 09.
> #
> ##
> { 'command': 'query-pci', 'returns': ['PciInfo'] }
Otherwise looks good to me except for the somewhat ugly rendering in
HTML mentioned in the commit message.
ACK