| Message ID | 20240703210144.339530-8-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | qapi: convert example sections to qmp-example rST directives | expand |
John Snow <jsnow@redhat.com> writes: > These examples require longer explanations or have explanations that > require markup to look reasonable when rendered and so use the longer > form of the ".. qmp-example::" directive. > > By using the :annotated: option, the content in the example block is > assumed *not* to be a code block literal and is instead parsed as normal > rST - with the exception that any code literal blocks after `::` will > assumed to be a QMP code literal block. > > Note: There's one title-less conversion in this patch that comes along > for the ride because it's part of a larger "Examples" block that was > better to convert all at once. > > See commit-5: "docs/qapidoc: create qmp-example directive", for a > detailed explanation of this custom directive syntax. > > See commit+1: "qapi: remove "Example" doc section" for a detailed > explanation of why. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > qapi/block.json | 26 ++++++++++++++++---------- > qapi/machine.json | 30 ++++++++++++++++++++---------- > qapi/migration.json | 7 +++++-- > qapi/virtio.json | 24 ++++++++++++++++++------ > 4 files changed, 59 insertions(+), 28 deletions(-) > > diff --git a/qapi/block.json b/qapi/block.json > index 5ddd061e964..d95e9fd8140 100644 > --- a/qapi/block.json > +++ b/qapi/block.json > @@ -545,31 +545,37 @@ > # > # Since: 4.0 > # > -# Example: > +# .. qmp-example:: > +# :annotated: > # > -# Set new histograms for all io types with intervals > -# [0, 10), [10, 50), [50, 100), [100, +inf): > +# Set new histograms for all io types with intervals > +# [0, 10), [10, 50), [50, 100), [100, +inf):: > # > # -> { "execute": "block-latency-histogram-set", > # "arguments": { "id": "drive0", > # "boundaries": [10, 50, 100] } } > # <- { "return": {} } > # > -# Example: > +# .. qmp-example:: > +# :annotated: > # > -# Set new histogram only for write, other histograms will remain > -# not changed (or not created): > +# Set new histogram only for write, other histograms will remain > +# not changed (or not created):: > # > # -> { "execute": "block-latency-histogram-set", > # "arguments": { "id": "drive0", > # "boundaries-write": [10, 50, 100] } } > # <- { "return": {} } > # > -# Example: > +# .. qmp-example:: > +# :annotated: > # > -# Set new histograms with the following intervals: > -# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) > -# write: [0, 1000), [1000, 5000), [5000, +inf) > +# Set new histograms with the following intervals: > +# > +# - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) > +# - write: [0, 1000), [1000, 5000), [5000, +inf) > +# > +# :: > # > # -> { "execute": "block-latency-histogram-set", > # "arguments": { "id": "drive0", # "boundaries": [10, 50, 100], # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # # .. qmp-example:: # :title: Remove all latency histograms # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } # <- { "return": {} } ## I think using :annotated: for this one as well will look better. [...] Reviewed-by: Markus Armbruster <armbru@redhat.com>
On Tue, Jul 9, 2024 at 7:35 AM Markus Armbruster <armbru@redhat.com> wrote: > John Snow <jsnow@redhat.com> writes: > > > These examples require longer explanations or have explanations that > > require markup to look reasonable when rendered and so use the longer > > form of the ".. qmp-example::" directive. > > > > By using the :annotated: option, the content in the example block is > > assumed *not* to be a code block literal and is instead parsed as normal > > rST - with the exception that any code literal blocks after `::` will > > assumed to be a QMP code literal block. > > > > Note: There's one title-less conversion in this patch that comes along > > for the ride because it's part of a larger "Examples" block that was > > better to convert all at once. > > > > See commit-5: "docs/qapidoc: create qmp-example directive", for a > > detailed explanation of this custom directive syntax. > > > > See commit+1: "qapi: remove "Example" doc section" for a detailed > > explanation of why. > > > > Signed-off-by: John Snow <jsnow@redhat.com> > > --- > > qapi/block.json | 26 ++++++++++++++++---------- > > qapi/machine.json | 30 ++++++++++++++++++++---------- > > qapi/migration.json | 7 +++++-- > > qapi/virtio.json | 24 ++++++++++++++++++------ > > 4 files changed, 59 insertions(+), 28 deletions(-) > > > > diff --git a/qapi/block.json b/qapi/block.json > > index 5ddd061e964..d95e9fd8140 100644 > > --- a/qapi/block.json > > +++ b/qapi/block.json > > @@ -545,31 +545,37 @@ > > # > > # Since: 4.0 > > # > > -# Example: > > +# .. qmp-example:: > > +# :annotated: > > # > > -# Set new histograms for all io types with intervals > > -# [0, 10), [10, 50), [50, 100), [100, +inf): > > +# Set new histograms for all io types with intervals > > +# [0, 10), [10, 50), [50, 100), [100, +inf):: > > # > > # -> { "execute": "block-latency-histogram-set", > > # "arguments": { "id": "drive0", > > # "boundaries": [10, 50, 100] } } > > # <- { "return": {} } > > # > > -# Example: > > +# .. qmp-example:: > > +# :annotated: > > # > > -# Set new histogram only for write, other histograms will remain > > -# not changed (or not created): > > +# Set new histogram only for write, other histograms will remain > > +# not changed (or not created):: > > # > > # -> { "execute": "block-latency-histogram-set", > > # "arguments": { "id": "drive0", > > # "boundaries-write": [10, 50, 100] } } > > # <- { "return": {} } > > # > > -# Example: > > +# .. qmp-example:: > > +# :annotated: > > # > > -# Set new histograms with the following intervals: > > -# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) > > -# write: [0, 1000), [1000, 5000), [5000, +inf) > > +# Set new histograms with the following intervals: > > +# > > +# - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) > > +# - write: [0, 1000), [1000, 5000), [5000, +inf) > > +# > > +# :: > > # > > # -> { "execute": "block-latency-histogram-set", > > # "arguments": { "id": "drive0", > # "boundaries": [10, 50, 100], > # "boundaries-write": [1000, 5000] } } > # <- { "return": {} } > # > # .. qmp-example:: > # :title: Remove all latency histograms > # > # -> { "execute": "block-latency-histogram-set", > # "arguments": { "id": "drive0" } } > # <- { "return": {} } > ## > > I think using :annotated: for this one as well will look better. > Sure, why not. I tried to minimize more complex rewrites as a rule, but it's no problem to change the styling to taste. > > [...] > > Reviewed-by: Markus Armbruster <armbru@redhat.com> > >
diff --git a/qapi/block.json b/qapi/block.json index 5ddd061e964..d95e9fd8140 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -545,31 +545,37 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histograms for all io types with intervals -# [0, 10), [10, 50), [50, 100), [100, +inf): +# Set new histograms for all io types with intervals +# [0, 10), [10, 50), [50, 100), [100, +inf):: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries": [10, 50, 100] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histogram only for write, other histograms will remain -# not changed (or not created): +# Set new histogram only for write, other histograms will remain +# not changed (or not created):: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries-write": [10, 50, 100] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histograms with the following intervals: -# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) -# write: [0, 1000), [1000, 5000), [5000, +inf) +# Set new histograms with the following intervals: +# +# - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) +# - write: [0, 1000), [1000, 5000), [5000, +inf) +# +# :: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", diff --git a/qapi/machine.json b/qapi/machine.json index 83f60b319c7..0a5ffe652b7 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1047,10 +1047,11 @@ # # Since: 2.7 # -# Examples: +# .. qmp-example:: +# :annotated: # -# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -# -cpu POWER8: +# For pseries machine type started with +# ``-smp 2,cores=2,maxcpus=4 -cpu POWER8``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1060,7 +1061,10 @@ # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} # ]} # -# For pc machine type started with -smp 1,maxcpus=2: +# .. qmp-example:: +# :annotated: +# +# For pc machine type started with ``-smp 1,maxcpus=2``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1075,8 +1079,11 @@ # } # ]} # -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -# -cpu qemu (Since: 2.11): +# .. qmp-example:: +# :annotated: +# +# For s390x-virtio-ccw machine type started with +# ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11):: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1130,12 +1137,15 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: +# :annotated: # -# -> { "execute": "balloon", "arguments": { "value": 536870912 } } -# <- { "return": {} } +# :: # -# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# -> { "execute": "balloon", "arguments": { "value": 536870912 } } +# <- { "return": {} } +# +# With a 2.5GiB guest this command inflated the ballon to 3GiB. ## { 'command': 'balloon', 'data': {'value': 'int'} } diff --git a/qapi/migration.json b/qapi/migration.json index 37ce8afa380..e208a86258a 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -2106,13 +2106,16 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, # "sample-pages": 512} } # <- { "return": {} } # -# Measure dirty rate using dirty bitmap for 500 milliseconds: +# .. qmp-example:: +# :annotated: +# +# Measure dirty rate using dirty bitmap for 500 milliseconds:: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, # "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } diff --git a/qapi/virtio.json b/qapi/virtio.json index d965c98ad2b..26df8b3064b 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -203,9 +203,11 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: +# :annotated: # -# 1. Poll for the status of virtio-crypto (no vhost-crypto active) +# Poll for the status of virtio-crypto (no vhost-crypto active) +# :: # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" } @@ -261,7 +263,11 @@ # } # } # -# 2. Poll for the status of virtio-net (vhost-net is active) +# .. qmp-example:: +# :annotated: +# +# Poll for the status of virtio-net (vhost-net is active) +# :: # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" } @@ -568,9 +574,11 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: +# :annotated: # -# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# :: # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", @@ -593,7 +601,11 @@ # } # } # -# 2. Get VirtQueueStatus for virtio-serial (no vhost) +# .. qmp-example:: +# :annotated: +# +# Get VirtQueueStatus for virtio-serial (no vhost) +# :: # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
These examples require longer explanations or have explanations that require markup to look reasonable when rendered and so use the longer form of the ".. qmp-example::" directive. By using the :annotated: option, the content in the example block is assumed *not* to be a code block literal and is instead parsed as normal rST - with the exception that any code literal blocks after `::` will assumed to be a QMP code literal block. Note: There's one title-less conversion in this patch that comes along for the ride because it's part of a larger "Examples" block that was better to convert all at once. See commit-5: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+1: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow <jsnow@redhat.com> --- qapi/block.json | 26 ++++++++++++++++---------- qapi/machine.json | 30 ++++++++++++++++++++---------- qapi/migration.json | 7 +++++-- qapi/virtio.json | 24 ++++++++++++++++++------ 4 files changed, 59 insertions(+), 28 deletions(-)