| Message ID | 20240619003012.1753577-8-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: convert "Note" and "Example" sections to rST | expand |
John Snow <jsnow@redhat.com> writes: > The new QMP documentation generator wants to parse all examples as > "QMP". We have an existing QMP lexer in docs/sphinx/qmp_lexer.py (Seen > in-use here: https://qemu-project.gitlab.io/qemu/interop/bitmaps.html) > that allows the use of "->", "<-" and "..." tokens to denote QMP > protocol flow with elisions, but otherwise defers to the JSON lexer. > > To utilize this lexer for the existing QAPI documentation, we need them > to conform to a standard so that they lex and render correctly. Once the > QMP lexer is active for examples, errant QMP/JSON will produce warning > messages and fail the build. > > Fix any invalid JSON found in QAPI documentation (identified by > attempting to lex all examples as QMP; see subsequent commits). Further, > the QMP lexer still supports elisions, but they must be represented as > the value "...", so three examples have been adjusted to support that > format here. > > Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com>
diff --git a/qapi/control.json b/qapi/control.json index 6bdbf077c2e..10c906fa0e7 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -145,7 +145,8 @@ # }, # { # "name":"system_powerdown" -# } +# }, +# ... # ] # } # diff --git a/qapi/machine.json b/qapi/machine.json index 453feb93473..172b38e343e 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1057,7 +1057,7 @@ # "vcpus-count": 1 }, # { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} -# ]}' +# ]} # # For pc machine type started with -smp 1,maxcpus=2: # diff --git a/qapi/migration.json b/qapi/migration.json index 470f746cc5f..7d4b567eb59 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -2087,7 +2087,7 @@ # Example: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, -# 'sample-pages': 512} } +# "sample-pages": 512} } # <- { "return": {} } # # Measure dirty rate using dirty bitmap for 500 milliseconds: diff --git a/qapi/misc.json b/qapi/misc.json index ec30e5c570a..4b41e15dcd4 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -287,7 +287,8 @@ # # Example: # -# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } } +# -> { "execute": "get-win32-socket", +# "arguments": { "info": "abcd123..", "fdname": "skclient" } } # <- { "return": {} } ## { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' } diff --git a/qapi/net.json b/qapi/net.json index 0f5a259475e..c19df435a53 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -1003,9 +1003,9 @@ # # Example: # -# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', -# 'data': {'netdev-id': 'netdev0'}, -# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } +# <- { "event": "NETDEV_STREAM_DISCONNECTED", +# "data": {"netdev-id": "netdev0"}, +# "timestamp": {"seconds": 1663330937, "microseconds": 526695} } ## { 'event': 'NETDEV_STREAM_DISCONNECTED', 'data': { 'netdev-id': 'str' } } diff --git a/qapi/rocker.json b/qapi/rocker.json index 5635cf174fd..f5225eb62cc 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -250,7 +250,7 @@ # "action": {"goto-tbl": 10}, # "mask": {"in-pport": 4294901760} # }, -# {...more...}, +# {...}, # ]} ## { 'command': 'query-rocker-of-dpa-flows', diff --git a/qapi/ui.json b/qapi/ui.json index f610bce118a..c12f5292571 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -361,7 +361,7 @@ # "channel-id": 0, # "tls": false # }, -# [ ... more channels follow ... ] +# ... # ] # } # }
The new QMP documentation generator wants to parse all examples as "QMP". We have an existing QMP lexer in docs/sphinx/qmp_lexer.py (Seen in-use here: https://qemu-project.gitlab.io/qemu/interop/bitmaps.html) that allows the use of "->", "<-" and "..." tokens to denote QMP protocol flow with elisions, but otherwise defers to the JSON lexer. To utilize this lexer for the existing QAPI documentation, we need them to conform to a standard so that they lex and render correctly. Once the QMP lexer is active for examples, errant QMP/JSON will produce warning messages and fail the build. Fix any invalid JSON found in QAPI documentation (identified by attempting to lex all examples as QMP; see subsequent commits). Further, the QMP lexer still supports elisions, but they must be represented as the value "...", so three examples have been adjusted to support that format here. Signed-off-by: John Snow <jsnow@redhat.com> --- qapi/control.json | 3 ++- qapi/machine.json | 2 +- qapi/migration.json | 2 +- qapi/misc.json | 3 ++- qapi/net.json | 6 +++--- qapi/rocker.json | 2 +- qapi/ui.json | 2 +- 7 files changed, 11 insertions(+), 9 deletions(-)