John Snow <js...@redhat.com> writes: > This is a directive that creates a syntactic sugar for creating > "Example" boxes very similar to the ones already used in the bitmaps.rst > document, please see e.g. > https://www.qemu.org/docs/master/interop/bitmaps.html#creation-block-dirty-bitmap-add > > In its simplest form, when a custom title is not needed or wanted, and > the example body is *solely* a QMP example: > > ``` > .. qmp-example:: > > {body} > ``` > > is syntactic sugar for: > > ``` > .. admonition:: Example: > > .. code-block:: QMP > > {body} > ``` > > When a custom, plaintext title that describes the example is desired, > this form: > > ``` > .. qmp-example:: > :title: Defrobnification > > {body} > ``` > > Is syntactic sugar for: > > ``` > .. admonition:: Example: Defrobnification > > .. code-block:: QMP > > {body} > ``` > > Lastly, when Examples are multi-step processes that require non-QMP > exposition, have lengthy titles, or otherwise involve prose with rST > markup (lists, cross-references, etc), the most complex form: > > ``` > .. qmp-example:: > :annotated: > > This example shows how to use `foo-command`:: > > {body} > > For more information, please see `frobnozz`. > ``` > > Is desugared to: > > ``` > .. admonition:: Example: > > This example shows how to use `foo-command`:: > > {body} > > For more information, please see `frobnozz`. > ``` > > Note that :annotated: and :title: options can be combined together, if > desired. > > The primary benefit here being documentation source consistently using > the same directive for all forms of examples to ensure consistent visual > styling, and ensuring all relevant prose is visually grouped alongside > the code literal block. > > Note that as of this commit, the code-block rST syntax "::" does not > apply QMP highlighting; you would need to use ".. code-block:: QMP". The > very next commit changes this behavior to assume all "::" code blocks > within this directive are QMP blocks. > > Signed-off-by: John Snow <js...@redhat.com>
Acked-by: Markus Armbruster <arm...@redhat.com>
