Re: [PATCH v3 21/33] hmp-commands-info.hx: Add rST documentation fragments

["Alex Bennée" <alex.bennee@linaro.org>]

Peter Maydell <peter.maydell@linaro.org> writes:

> Add the rST versions of the documentation fragments.  Once we've
> converted fully from Texinfo to rST we can remove the ETEXI
> fragments; for the moment we need both.
>
> Note that most of the SRST fragments are 2-space indented so that the
> 'info foo' documentation entries appear as a sublist under the 'info'
> entry in the top level list.
>
> Again, all we need to do to put the documentation in the Sphinx manual
> is a one-line hxtool-doc invocation.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

> ---
>  Makefile                |   2 +-
>  docs/system/monitor.rst |   4 +-
>  hmp-commands-info.hx    | 271 ++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 273 insertions(+), 4 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index 22427376b48..98ef06ab8e8 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1071,7 +1071,7 @@ $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
>  $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
>  	$(call build-manual,specs,html)
>  
> -$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(SRC_PATH)/hmp-commands.hx
> +$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/hmp-commands-info.hx
>  	$(call build-manual,system,html)
>  
>  $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc
> diff --git a/docs/system/monitor.rst b/docs/system/monitor.rst
> index 52b0f18cfec..0bcd5da2164 100644
> --- a/docs/system/monitor.rst
> +++ b/docs/system/monitor.rst
> @@ -21,9 +21,7 @@ The following commands are available:
>  
>  .. hxtool-doc:: hmp-commands.hx
>  
> -..
> -  TODO: convert and reference hmp-commands-info.hx
> -
> +.. hxtool-doc:: hmp-commands-info.hx
>  
>  Integer expressions
>  ~~~~~~~~~~~~~~~~~~~
> diff --git a/hmp-commands-info.hx b/hmp-commands-info.hx
> index 257ee7d7a3f..1730f866cde 100644
> --- a/hmp-commands-info.hx
> +++ b/hmp-commands-info.hx
> @@ -4,6 +4,12 @@ HXCOMM discarded from C version
>  HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
>  HXCOMM monitor info commands
>  HXCOMM HXCOMM can be used for comments, discarded from both texi and C
> +HXCOMM
> +HXCOMM In this file, generally SRST fragments should have two extra
> +HXCOMM spaces of indent, so that the documentation list item for "info foo"
> +HXCOMM appears inside the documentation list item for the top level
> +HXCOMM "info" documentation entry. The exception is the first SRST
> +HXCOMM fragment that defines that top level entry.
>  
>  STEXI
>  @table @option
> @@ -12,6 +18,11 @@ STEXI
>  Show various information about the system state.
>  @table @option
>  ETEXI
> +SRST
> +``info`` *subcommand*
> +  Show various information about the system state.
> +
> +ERST
>  
>      {
>          .name       = "version",
> @@ -27,6 +38,10 @@ STEXI
>  @findex info version
>  Show the version of QEMU.
>  ETEXI
> +SRST
> +  ``info version``
> +    Show the version of QEMU.
> +ERST
>  
>      {
>          .name       = "network",
> @@ -41,6 +56,10 @@ STEXI
>  @findex info network
>  Show the network state.
>  ETEXI
> +SRST
> +  ``info network``
> +    Show the network state.
> +ERST
>  
>      {
>          .name       = "chardev",
> @@ -56,6 +75,10 @@ STEXI
>  @findex info chardev
>  Show the character devices.
>  ETEXI
> +SRST
> +  ``info chardev``
> +    Show the character devices.
> +ERST
>  
>      {
>          .name       = "block",
> @@ -71,6 +94,10 @@ STEXI
>  @findex info block
>  Show info of one block device or all block devices.
>  ETEXI
> +SRST
> +  ``info block``
> +    Show info of one block device or all block devices.
> +ERST
>  
>      {
>          .name       = "blockstats",
> @@ -85,6 +112,10 @@ STEXI
>  @findex info blockstats
>  Show block device statistics.
>  ETEXI
> +SRST
> +  ``info blockstats``
> +    Show block device statistics.
> +ERST
>  
>      {
>          .name       = "block-jobs",
> @@ -99,6 +130,10 @@ STEXI
>  @findex info block-jobs
>  Show progress of ongoing block device operations.
>  ETEXI
> +SRST
> +  ``info block-jobs``
> +    Show progress of ongoing block device operations.
> +ERST
>  
>      {
>          .name       = "registers",
> @@ -113,6 +148,10 @@ STEXI
>  @findex info registers
>  Show the cpu registers.
>  ETEXI
> +SRST
> +  ``info registers``
> +    Show the cpu registers.
> +ERST
>  
>  #if defined(TARGET_I386)
>      {
> @@ -130,6 +169,10 @@ STEXI
>  @findex info lapic
>  Show local APIC state
>  ETEXI
> +SRST
> +  ``info lapic``
> +    Show local APIC state
> +ERST
>  
>  #if defined(TARGET_I386)
>      {
> @@ -146,6 +189,10 @@ STEXI
>  @findex info ioapic
>  Show io APIC state
>  ETEXI
> +SRST
> +  ``info ioapic``
> +    Show io APIC state
> +ERST
>  
>      {
>          .name       = "cpus",
> @@ -160,6 +207,10 @@ STEXI
>  @findex info cpus
>  Show infos for each CPU.
>  ETEXI
> +SRST
> +  ``info cpus``
> +    Show infos for each CPU.
> +ERST
>  
>      {
>          .name       = "history",
> @@ -175,6 +226,10 @@ STEXI
>  @findex info history
>  Show the command line history.
>  ETEXI
> +SRST
> +  ``info history``
> +    Show the command line history.
> +ERST
>  
>      {
>          .name       = "irq",
> @@ -189,6 +244,10 @@ STEXI
>  @findex info irq
>  Show the interrupts statistics (if available).
>  ETEXI
> +SRST
> +  ``info irq``
> +    Show the interrupts statistics (if available).
> +ERST
>  
>      {
>          .name       = "pic",
> @@ -203,6 +262,10 @@ STEXI
>  @findex info pic
>  Show PIC state.
>  ETEXI
> +SRST
> +  ``info pic``
> +    Show PIC state.
> +ERST
>  
>      {
>          .name       = "rdma",
> @@ -217,6 +280,10 @@ STEXI
>  @findex info rdma
>  Show RDMA state.
>  ETEXI
> +SRST
> +  ``info rdma``
> +    Show RDMA state.
> +ERST
>  
>      {
>          .name       = "pci",
> @@ -231,6 +298,10 @@ STEXI
>  @findex info pci
>  Show PCI information.
>  ETEXI
> +SRST
> +  ``info pci``
> +    Show PCI information.
> +ERST
>  
>  #if defined(TARGET_I386) || defined(TARGET_SH4) || defined(TARGET_SPARC) || \
>      defined(TARGET_PPC) || defined(TARGET_XTENSA) || defined(TARGET_M68K)
> @@ -248,6 +319,10 @@ STEXI
>  @findex info tlb
>  Show virtual to physical memory mappings.
>  ETEXI
> +SRST
> +  ``info tlb``
> +    Show virtual to physical memory mappings.
> +ERST
>  
>  #if defined(TARGET_I386) || defined(TARGET_RISCV)
>      {
> @@ -264,6 +339,10 @@ STEXI
>  @findex info mem
>  Show the active virtual memory mappings.
>  ETEXI
> +SRST
> +  ``info mem``
> +    Show the active virtual memory mappings.
> +ERST
>  
>      {
>          .name       = "mtree",
> @@ -280,6 +359,10 @@ STEXI
>  @findex info mtree
>  Show memory tree.
>  ETEXI
> +SRST
> +  ``info mtree``
> +    Show memory tree.
> +ERST
>  
>  #if defined(CONFIG_TCG)
>      {
> @@ -296,6 +379,10 @@ STEXI
>  @findex info jit
>  Show dynamic compiler info.
>  ETEXI
> +SRST
> +  ``info jit``
> +    Show dynamic compiler info.
> +ERST
>  
>  #if defined(CONFIG_TCG)
>      {
> @@ -312,6 +399,10 @@ STEXI
>  @findex info opcount
>  Show dynamic compiler opcode counters
>  ETEXI
> +SRST
> +  ``info opcount``
> +    Show dynamic compiler opcode counters
> +ERST
>  
>      {
>          .name       = "sync-profile",
> @@ -334,6 +425,20 @@ sorted by total wait time.
>  When different objects that share the same call site are coalesced, the "Object"
>  field shows---enclosed in brackets---the number of objects being coalesced.
>  ETEXI
> +SRST
> +  ``info sync-profile [-m|-n]`` [*max*]
> +    Show synchronization profiling info, up to *max* entries (default: 10),
> +    sorted by total wait time.
> +
> +    ``-m``
> +      sort by mean wait time
> +    ``-n``
> +      do not coalesce objects with the same call site
> +
> +    When different objects that share the same call site are coalesced,
> +    the "Object" field shows---enclosed in brackets---the number of objects
> +    being coalesced.
> +ERST
>  
>      {
>          .name       = "kvm",
> @@ -348,6 +453,10 @@ STEXI
>  @findex info kvm
>  Show KVM information.
>  ETEXI
> +SRST
> +  ``info kvm``
> +    Show KVM information.
> +ERST
>  
>      {
>          .name       = "numa",
> @@ -362,6 +471,10 @@ STEXI
>  @findex info numa
>  Show NUMA information.
>  ETEXI
> +SRST
> +  ``info numa``
> +    Show NUMA information.
> +ERST
>  
>      {
>          .name       = "usb",
> @@ -376,6 +489,10 @@ STEXI
>  @findex info usb
>  Show guest USB devices.
>  ETEXI
> +SRST
> +  ``info usb``
> +    Show guest USB devices.
> +ERST
>  
>      {
>          .name       = "usbhost",
> @@ -390,6 +507,10 @@ STEXI
>  @findex info usbhost
>  Show host USB devices.
>  ETEXI
> +SRST
> +  ``info usbhost``
> +    Show host USB devices.
> +ERST
>  
>      {
>          .name       = "profile",
> @@ -404,6 +525,10 @@ STEXI
>  @findex info profile
>  Show profiling information.
>  ETEXI
> +SRST
> +  ``info profile``
> +    Show profiling information.
> +ERST
>  
>      {
>          .name       = "capture",
> @@ -418,6 +543,10 @@ STEXI
>  @findex info capture
>  Show capture information.
>  ETEXI
> +SRST
> +  ``info capture``
> +    Show capture information.
> +ERST
>  
>      {
>          .name       = "snapshots",
> @@ -432,6 +561,10 @@ STEXI
>  @findex info snapshots
>  Show the currently saved VM snapshots.
>  ETEXI
> +SRST
> +  ``info snapshots``
> +    Show the currently saved VM snapshots.
> +ERST
>  
>      {
>          .name       = "status",
> @@ -447,6 +580,10 @@ STEXI
>  @findex info status
>  Show the current VM status (running|paused).
>  ETEXI
> +SRST
> +  ``info status``
> +    Show the current VM status (running|paused).
> +ERST
>  
>      {
>          .name       = "mice",
> @@ -461,6 +598,10 @@ STEXI
>  @findex info mice
>  Show which guest mouse is receiving events.
>  ETEXI
> +SRST
> +  ``info mice``
> +    Show which guest mouse is receiving events.
> +ERST
>  
>  #if defined(CONFIG_VNC)
>      {
> @@ -477,6 +618,10 @@ STEXI
>  @findex info vnc
>  Show the vnc server status.
>  ETEXI
> +SRST
> +  ``info vnc``
> +    Show the vnc server status.
> +ERST
>  
>  #if defined(CONFIG_SPICE)
>      {
> @@ -493,6 +638,10 @@ STEXI
>  @findex info spice
>  Show the spice server status.
>  ETEXI
> +SRST
> +  ``info spice``
> +    Show the spice server status.
> +ERST
>  
>      {
>          .name       = "name",
> @@ -508,6 +657,10 @@ STEXI
>  @findex info name
>  Show the current VM name.
>  ETEXI
> +SRST
> +  ``info name``
> +    Show the current VM name.
> +ERST
>  
>      {
>          .name       = "uuid",
> @@ -523,6 +676,10 @@ STEXI
>  @findex info uuid
>  Show the current VM UUID.
>  ETEXI
> +SRST
> +  ``info uuid``
> +    Show the current VM UUID.
> +ERST
>  
>      {
>          .name       = "cpustats",
> @@ -537,6 +694,10 @@ STEXI
>  @findex info cpustats
>  Show CPU statistics.
>  ETEXI
> +SRST
> +  ``info cpustats``
> +    Show CPU statistics.
> +ERST
>  
>  #if defined(CONFIG_SLIRP)
>      {
> @@ -553,6 +714,10 @@ STEXI
>  @findex info usernet
>  Show user network stack connection states.
>  ETEXI
> +SRST
> +  ``info usernet``
> +    Show user network stack connection states.
> +ERST
>  
>      {
>          .name       = "migrate",
> @@ -567,6 +732,10 @@ STEXI
>  @findex info migrate
>  Show migration status.
>  ETEXI
> +SRST
> +  ``info migrate``
> +    Show migration status.
> +ERST
>  
>      {
>          .name       = "migrate_capabilities",
> @@ -581,6 +750,10 @@ STEXI
>  @findex info migrate_capabilities
>  Show current migration capabilities.
>  ETEXI
> +SRST
> +  ``info migrate_capabilities``
> +    Show current migration capabilities.
> +ERST
>  
>      {
>          .name       = "migrate_parameters",
> @@ -595,6 +768,10 @@ STEXI
>  @findex info migrate_parameters
>  Show current migration parameters.
>  ETEXI
> +SRST
> +  ``info migrate_parameters``
> +    Show current migration parameters.
> +ERST
>  
>      {
>          .name       = "migrate_cache_size",
> @@ -609,6 +786,10 @@ STEXI
>  @findex info migrate_cache_size
>  Show current migration xbzrle cache size.
>  ETEXI
> +SRST
> +  ``info migrate_cache_size``
> +    Show current migration xbzrle cache size.
> +ERST
>  
>      {
>          .name       = "balloon",
> @@ -623,6 +804,10 @@ STEXI
>  @findex info balloon
>  Show balloon information.
>  ETEXI
> +SRST
> +  ``info balloon``
> +    Show balloon information.
> +ERST
>  
>      {
>          .name       = "qtree",
> @@ -637,6 +822,10 @@ STEXI
>  @findex info qtree
>  Show device tree.
>  ETEXI
> +SRST
> +  ``info qtree``
> +    Show device tree.
> +ERST
>  
>      {
>          .name       = "qdm",
> @@ -651,6 +840,10 @@ STEXI
>  @findex info qdm
>  Show qdev device model list.
>  ETEXI
> +SRST
> +  ``info qdm``
> +    Show qdev device model list.
> +ERST
>  
>      {
>          .name       = "qom-tree",
> @@ -666,6 +859,10 @@ STEXI
>  @findex info qom-tree
>  Show QOM composition tree.
>  ETEXI
> +SRST
> +  ``info qom-tree``
> +    Show QOM composition tree.
> +ERST
>  
>      {
>          .name       = "roms",
> @@ -680,6 +877,10 @@ STEXI
>  @findex info roms
>  Show roms.
>  ETEXI
> +SRST
> +  ``info roms``
> +    Show roms.
> +ERST
>  
>      {
>          .name       = "trace-events",
> @@ -696,6 +897,10 @@ STEXI
>  @findex info trace-events
>  Show available trace-events & their state.
>  ETEXI
> +SRST
> +  ``info trace-events``
> +    Show available trace-events & their state.
> +ERST
>  
>      {
>          .name       = "tpm",
> @@ -710,6 +915,10 @@ STEXI
>  @findex info tpm
>  Show the TPM device.
>  ETEXI
> +SRST
> +  ``info tpm``
> +    Show the TPM device.
> +ERST
>  
>      {
>          .name       = "memdev",
> @@ -725,6 +934,10 @@ STEXI
>  @findex info memdev
>  Show memory backends
>  ETEXI
> +SRST
> +  ``info memdev``
> +    Show memory backends
> +ERST
>  
>      {
>          .name       = "memory-devices",
> @@ -739,6 +952,10 @@ STEXI
>  @findex info memory-devices
>  Show memory devices.
>  ETEXI
> +SRST
> +  ``info memory-devices``
> +    Show memory devices.
> +ERST
>  
>      {
>          .name       = "iothreads",
> @@ -754,6 +971,10 @@ STEXI
>  @findex info iothreads
>  Show iothread's identifiers.
>  ETEXI
> +SRST
> +  ``info iothreads``
> +    Show iothread's identifiers.
> +ERST
>  
>      {
>          .name       = "rocker",
> @@ -768,6 +989,10 @@ STEXI
>  @findex info rocker
>  Show rocker switch.
>  ETEXI
> +SRST
> +  ``info rocker`` *name*
> +    Show rocker switch.
> +ERST
>  
>      {
>          .name       = "rocker-ports",
> @@ -782,6 +1007,10 @@ STEXI
>  @findex info rocker-ports
>  Show rocker ports.
>  ETEXI
> +SRST
> +  ``info rocker-ports`` *name*-ports
> +    Show rocker ports.
> +ERST
>  
>      {
>          .name       = "rocker-of-dpa-flows",
> @@ -796,6 +1025,10 @@ STEXI
>  @findex info rocker-of-dpa-flows
>  Show rocker OF-DPA flow tables.
>  ETEXI
> +SRST
> +  ``info rocker-of-dpa-flows`` *name* [*tbl_id*]
> +    Show rocker OF-DPA flow tables.
> +ERST
>  
>      {
>          .name       = "rocker-of-dpa-groups",
> @@ -810,6 +1043,10 @@ STEXI
>  @findex info rocker-of-dpa-groups
>  Show rocker OF-DPA groups.
>  ETEXI
> +SRST
> +  ``info rocker-of-dpa-groups`` *name* [*type*]
> +    Show rocker OF-DPA groups.
> +ERST
>  
>  #if defined(TARGET_S390X)
>      {
> @@ -826,6 +1063,10 @@ STEXI
>  @findex info skeys
>  Display the value of a storage key (s390 only)
>  ETEXI
> +SRST
> +  ``info skeys`` *address*
> +    Display the value of a storage key (s390 only)
> +ERST
>  
>  #if defined(TARGET_S390X)
>      {
> @@ -842,6 +1083,11 @@ STEXI
>  @findex info cmma
>  Display the values of the CMMA storage attributes for a range of pages (s390 only)
>  ETEXI
> +SRST
> +  ``info cmma`` *address*
> +    Display the values of the CMMA storage attributes for a range of
> +    pages (s390 only)
> +ERST
>  
>      {
>          .name       = "dump",
> @@ -856,6 +1102,10 @@ STEXI
>  @findex info dump
>  Display the latest dump status.
>  ETEXI
> +SRST
> +  ``info dump``
> +    Display the latest dump status.
> +ERST
>  
>      {
>          .name       = "ramblock",
> @@ -870,6 +1120,10 @@ STEXI
>  @findex info ramblock
>  Dump all the ramblocks of the system.
>  ETEXI
> +SRST
> +  ``info ramblock``
> +    Dump all the ramblocks of the system.
> +ERST
>  
>      {
>          .name       = "hotpluggable-cpus",
> @@ -885,6 +1139,10 @@ STEXI
>  @findex info hotpluggable-cpus
>  Show information about hotpluggable CPUs
>  ETEXI
> +SRST
> +  ``info hotpluggable-cpus``
> +    Show information about hotpluggable CPUs
> +ERST
>  
>      {
>          .name       = "vm-generation-id",
> @@ -899,6 +1157,10 @@ STEXI
>  @findex info vm-generation-id
>  Show Virtual Machine Generation ID
>  ETEXI
> +SRST
> +  ``info vm-generation-id``
> +    Show Virtual Machine Generation ID
> +ERST
>  
>      {
>          .name       = "memory_size_summary",
> @@ -915,6 +1177,11 @@ STEXI
>  Display the amount of initially allocated and present hotpluggable (if
>  enabled) memory in bytes.
>  ETEXI
> +SRST
> +  ``info memory_size_summary``
> +    Display the amount of initially allocated and present hotpluggable (if
> +    enabled) memory in bytes.
> +ERST
>  
>  #if defined(TARGET_I386)
>      {
> @@ -931,6 +1198,10 @@ STEXI
>  @findex info sev
>  Show SEV information.
>  ETEXI
> +SRST
> +  ``info sev``
> +    Show SEV information.
> +ERST
>  
>  STEXI
>  @end table


-- 
Alex Bennée