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. > > 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? > > 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 <js...@redhat.com> > Acked-by: Stefan Hajnoczi <stefa...@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. [...]