diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index f9cfe8721f..231cc0fecf 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental". This convention has been replaced by special feature "unstable". Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let -you violate naming rules. Use for new code is strongly discouraged. See -`Pragma directives`_ for details. +you violate naming rules. Use for new code is strongly discouraged. +See `Pragma directives`_ for details. Downstream extensions @@ -1013,7 +1013,7 @@ like this:: document the success and the error response, respectively. "Errors" sections should be formatted as an rST list, each entry -detailing a relevant error condition. For example:: +detailing a relevant error condition. For example:: # Errors: # - If @device does not exist, DeviceNotFound @@ -1026,31 +1026,28 @@ definition. QMP). In other sections, the text is formatted, and rST markup can be used. -QMP Examples can be added by using the ``.. qmp-example::`` -directive. In its simplest form, this can be used to contain a single -QMP code block which accepts standard JSON syntax with additional server -directionality indicators (``->`` and ``<-``), and elisions (``...``). +QMP Examples can be added by using the ``.. qmp-example::`` directive. +In its simplest form, this can be used to contain a single QMP code +block which accepts standard JSON syntax with additional server +directionality indicators (``->`` and ``<-``), and elisions. An +elision is commonly ``...``, but it can also be or a pair of ``...`` +with text in between. Optionally, a plaintext title may be provided by using the ``:title:`` -directive option. If the title is omitted, the example title will +directive option. If the title is omitted, the example title will default to "Example:". A simple QMP example:: # .. qmp-example:: - # :title: Using query-block # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-name" } + # <- { "return": { "name": "Fred" } } -More complex or multi-step examples where exposition is needed before or -between QMP code blocks can be created by using the ``:annotated:`` -directive option. When using this option, nested QMP code blocks must be -entered explicitly with rST's ``::`` syntax. - -Highlighting in non-QMP languages can be accomplished by using the -``.. code-block:: lang`` directive, and non-highlighted text can be -achieved by omitting the language argument. +More complex or multi-step examples where exposition is needed before +or between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocks must +be entered explicitly with rST's ``::`` syntax. For example:: @@ -1061,11 +1058,21 @@ For example:: # This is a more complex example that can use # ``arbitrary rST syntax`` in its exposition:: # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-block" } + # <- { "return": [ + # { + # "device": "ide0-hd0", + # ... + # } + # ... more ... + # ] } # # Above, lengthy output has been omitted for brevity. +Highlighting in non-QMP languages can be accomplished by using the +``.. code-block:: lang`` directive, and non-highlighted text can be +achieved by omitting the language argument. + Examples of complete definition documentation:: @@ -1466,7 +1473,9 @@ As an example, we'll use the following schema, which describes a single complex user-defined type, along with command which takes a list of that type as a parameter, and returns a single element of that type. The user is responsible for writing the implementation of -qmp_my_command(); everything else is produced by the generator. :: +qmp_my_command(); everything else is produced by the generator. + +:: $ cat example-schema.json { 'struct': 'UserDefOne', diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 19b5c7a549..25f6e24b03 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -1,9 +1,6 @@ QEMU Guest Agent Protocol Reference =================================== -.. contents:: - :depth: 3 - .. qapi-doc:: qga/qapi-schema.json :transmogrify: :namespace: QGA diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index ef8792b53f..3bc1ca12b1 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -4,7 +4,7 @@ QEMU QMP Reference Manual ========================= .. contents:: - :depth: 3 + :local: .. qapi-doc:: qapi/qapi-schema.json :transmogrify: diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index d0228d63b8..dc7bde262a 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -2,7 +2,7 @@ QEMU Storage Daemon QMP Reference Manual ======================================== .. contents:: - :depth: 3 + :local: .. qapi-doc:: storage-daemon/qapi/qapi-schema.json :transmogrify: diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py index a59de8a079..7b3b808d12 100644 --- a/docs/sphinx/qmp_lexer.py +++ b/docs/sphinx/qmp_lexer.py @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer): 'root': [ (r'-> ', token.Generic.Prompt), (r'<- ', token.Generic.Prompt), - (r' ?\.{3} ?', token.Generic.Prompt), + (r'\.{3}( .* \.{3})?', token.Comment.Multiline), ] } diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index c41c01eb2a..7bc600bb76 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -3,37 +3,24 @@ ## # = Introduction # -# This document describes all commands currently supported by QMP. +# This manual describes the commands and events supported by the QEMU +# Monitor Protocol (QMP). # # For locating a particular item, please see the `qapi-qmp-index`. # -# Most of the time their usage is exactly the same as in the user -# Monitor, this means that any other document which also describe -# commands (the manpage, QEMU's manual, etc) can and should be -# consulted. +# The following notation is used in examples: # -# QMP has two types of commands: regular and query commands. Regular -# commands usually change the Virtual Machine's state someway, while -# query commands just return information. The sections below are -# divided accordingly. +# .. qmp-example:: # -# It's important to observe that all communication examples are -# formatted in a reader-friendly way, so that they're easier to -# understand. However, in real protocol usage, they're emitted as a -# single line. +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... # -# Also, the following notation is used to denote data flow: -# -# Example: -# -# :: -# -# -> data issued by the Client -# <- Server data response +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. # # Please refer to the # :doc:`QEMU Machine Protocol Specification ` -# for detailed information on the Server command and response formats. +# for the general format of commands, responses, and events. ## { 'include': 'pragma.json' } diff --git a/qapi/rocker.json b/qapi/rocker.json index 51aa5b4930..0c7ef1f77c 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -254,7 +254,7 @@ # "action": {"goto-tbl": 10}, # "mask": {"in-pport": 4294901760} # }, -# {...}, +# ... # ]} ## { 'command': 'query-rocker-of-dpa-flows', diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 35ec0e7db3..5316bfacbf 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,10 +2,24 @@ # vim: filetype=python ## -# = QEMU guest agent protocol commands and structs +# This manual describes the commands supported by the QEMU Guest +# Agent Protocol. # -# For a concise listing of all commands, events, and types in the QEMU -# guest agent, please consult the `qapi-qga-index`. +# For locating a particular item, please see the `qapi-qga-index`. +# +# The following notation is used in examples: +# +# .. qmp-example:: +# +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... +# +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` +# for the general format of commands, responses, and events. ## { 'pragma': { 'doc-required': true } } diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json index 2a562ee32e..0427594c98 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -14,10 +14,26 @@ # storage daemon. ## -# = QEMU storage daemon protocol commands and structs +# = Introduction # -# For a concise listing of all commands, events, and types in the QEMU -# storage daemon, please consult the `qapi-qsd-index`. +# This manual describes the commands and events supported by the QEMU +# storage daemon QMP. +# +# For locating a particular item, please see the `qapi-qsd-index`. +# +# The following notation is used in examples: +# +# .. qmp-example:: +# +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... +# +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` +# for the general format of commands, responses, and events. ## diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 0a4f139f83..14b808f909 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -212,7 +212,7 @@ # # -> "this example" # -# <- "has no title" +# <- ... has no title ... ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 5773f1dd6d..dc8352eed4 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -217,7 +217,7 @@ another feature -> "this example" - <- "has no title" + <- ... has no title ... doc symbol=EVT_BOXED body= diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index cb37db606a..17a1d56ef1 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -264,7 +264,7 @@ Example:: -> "this example" - <- "has no title" + <- ... has no title ... "EVT_BOXED" (Event)