John Snow <js...@redhat.com> writes: > Fully eliminate the "Example" sections in QAPI doc blocks now that they > have all been converted to arbitrary rST syntax using the > ".. qmp-example::" directive. Update tests to match. > > Migrating to the new syntax > --------------------------- > > The old "Example:" or "Examples:" section syntax is now caught as an > error, but "Example::" is stil permitted as explicit rST syntax for an > un-lexed, generic preformatted text block. > > ('Example' is not special in this case, any sentence that ends with "::" > will start an indented code block in rST.) > > Arbitrary rST for Examples is now possible, but it's strongly > recommended that documentation authors use the ".. qmp-example::" > directive for consistent visual formatting in rendered HTML docs. The > ":title:" directive option may be used to add extra information into the > title bar for the example. The ":annotated:" option can be used to write > arbitrary rST instead, with nested "::" blocks applying QMP formatting > where desired. > > Other choices available are ".. code-block:: QMP" which will not create > an "Example:" box, or the short-form "::" code-block syntax which will > not apply QMP highlighting when used outside of the qmp-example > directive. > > Why? > ---- > > 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. > > 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 qmp-example can be titled or annotated independently without > bypassing the QMP lexer/validator. > > (i.e. code blocks are now for *code* only, so we don't have to > sacrifice exposition for having lexically valid examples.) > > NOTE: As with the "Notes" conversion (d461c279737), this patch (and the > three preceding) may change the rendering order for Examples in > the current generator. The forthcoming qapidoc rewrite will fix > this by always generating documentation in source order. > > Signed-off-by: John Snow <js...@redhat.com>
Reviewed-by: Markus Armbruster <arm...@redhat.com>