Re: [PATCH] docs: convert writing-qmp-commands.txt to writing-qmp-commands.rst

[Markus Armbruster]

John Snow  writes:

> This does about the bare minimum, converting section headers to ReST
> ones and adding an indent for code blocks.
>
> Signed-off-by: John Snow 
> ---
>  docs/devel/index.rst  |   1 +
>  ...-commands.txt => writing-qmp-commands.rst} | 581 +-
>  2 files changed, 304 insertions(+), 278 deletions(-)
>  rename docs/devel/{writing-qmp-commands.txt => writing-qmp-commands.rst} 
> (61%)
>
> diff --git a/docs/devel/index.rst b/docs/devel/index.rst
> index 153979caf4b..331004ad072 100644
> --- a/docs/devel/index.rst
> +++ b/docs/devel/index.rst
> @@ -42,3 +42,4 @@ modifying QEMU's source code.
> multi-process
> ebpf_rss
> vfio-migration
> +   writing-qmp-commands

Conflicts with your "[PATCH 0/3] docs: convert qapi-code-gen.txt to
qapi-code-gen.rst", resolution is straightforward.  Still, consider
avoiding even trivial conflicts by stacking your work.  Use Based-on:
tags to specify the dependencies.

Same question as for the other series: for 6.1, or "don't rock the boat
now"?

Regardless, both queued.  Thanks!

Re: [PATCH] docs: convert writing-qmp-commands.txt to writing-qmp-commands.rst

[Connor Kuehl]

On 7/21/21 11:50 AM, John Snow wrote:

This does about the bare minimum, converting section headers to ReST
ones and adding an indent for code blocks.

Signed-off-by: John Snow 
---


Looks like ReST! The generated document also looks good to me.

Reviewed-by: Connor Kuehl 

[PATCH] docs: convert writing-qmp-commands.txt to writing-qmp-commands.rst

[John Snow]

This does about the bare minimum, converting section headers to ReST
ones and adding an indent for code blocks.

Signed-off-by: John Snow 
---
 docs/devel/index.rst  |   1 +
 ...-commands.txt => writing-qmp-commands.rst} | 581 +-
 2 files changed, 304 insertions(+), 278 deletions(-)
 rename docs/devel/{writing-qmp-commands.txt => writing-qmp-commands.rst} (61%)

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 153979caf4b..331004ad072 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -42,3 +42,4 @@ modifying QEMU's source code.
multi-process
ebpf_rss
vfio-migration
+   writing-qmp-commands
diff --git a/docs/devel/writing-qmp-commands.txt 
b/docs/devel/writing-qmp-commands.rst
similarity index 61%
rename from docs/devel/writing-qmp-commands.txt
rename to docs/devel/writing-qmp-commands.rst
index b1e31d56c0f..6a10a06c483 100644
--- a/docs/devel/writing-qmp-commands.txt
+++ b/docs/devel/writing-qmp-commands.rst
@@ -1,4 +1,5 @@
-= How to write QMP commands using the QAPI framework =
+How to write QMP commands using the QAPI framework
+==
 
 This document is a step-by-step guide on how to write new QMP commands using
 the QAPI framework. It also shows how to implement new style HMP commands.
@@ -10,7 +11,9 @@ For an in-depth introduction to the QAPI framework, please 
refer to
 docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol,
 start with docs/interop/qmp-intro.txt.
 
-== Overview ==
+
+Overview
+
 
 Generally speaking, the following steps should be taken in order to write a
 new QMP command.
@@ -31,55 +34,59 @@ new QMP command.
 The following sections will demonstrate each of the steps above. We will start
 very simple and get more complex as we progress.
 
-=== Testing ===
+
+Testing
+---
 
 For all the examples in the next sections, the test setup is the same and is
 shown here.
 
-First, QEMU should be started like this:
+First, QEMU should be started like this::
 
-# qemu-system-TARGET [...] \
--chardev socket,id=qmp,port=,host=localhost,server=on \
--mon chardev=qmp,mode=control,pretty=on
+ # qemu-system-TARGET [...] \
+ -chardev socket,id=qmp,port=,host=localhost,server=on \
+ -mon chardev=qmp,mode=control,pretty=on
 
-Then, in a different terminal:
+Then, in a different terminal::
 
-$ telnet localhost 
-Trying 127.0.0.1...
-Connected to localhost.
-Escape character is '^]'.
-{
-"QMP": {
-"version": {
-"qemu": {
-"micro": 50, 
-"minor": 15, 
-"major": 0
-}, 
-"package": ""
-}, 
-"capabilities": [
-]
-}
-}
+ $ telnet localhost 
+ Trying 127.0.0.1...
+ Connected to localhost.
+ Escape character is '^]'.
+ {
+ "QMP": {
+ "version": {
+ "qemu": {
+ "micro": 50,
+ "minor": 15,
+ "major": 0
+ },
+ "package": ""
+ },
+ "capabilities": [
+ ]
+ }
+ }
 
 The above output is the QMP server saying you're connected. The server is
-actually in capabilities negotiation mode. To enter in command mode type:
+actually in capabilities negotiation mode. To enter in command mode type::
 
-{ "execute": "qmp_capabilities" }
+ { "execute": "qmp_capabilities" }
 
-Then the server should respond:
+Then the server should respond::
 
-{
-"return": {
-}
-}
+ {
+ "return": {
+ }
+ }
 
 Which is QMP's way of saying "the latest command executed OK and didn't return
 any data". Now you're ready to enter the QMP example commands as explained in
 the following sections.
 
-== Writing a command that doesn't return data ==
+
+Writing a command that doesn't return data
+--
 
 That's the most simple QMP command that can be written. Usually, this kind of
 command carries some meaningful action in QEMU but here it will just print
@@ -90,9 +97,9 @@ return any data.
 
 The first step is defining the command in the appropriate QAPI schema
 module.  We pick module qapi/misc.json, and add the following line at
-the bottom:
+the bottom::
 
-{ 'command': 'hello-world' }
+ { 'command': 'hello-world' }
 
 The "command" keyword defines a new QMP command. It's an JSON object. All
 schema entries are JSON objects. The line above will instruct the QAPI to
@@ -102,19 +109,19 @@ protocol data.
 The next step is to write the "hello-world" implementation. As explained
 earlier, it's preferable for commands to live in QEMU subsystems. But
 "hello-world" doesn't pertain to any, so we put its implementation in
-monitor/qmp-cmds.c:
+monitor/qmp-cmds.c::
 
-void qmp_hello_world(Error **errp)
-{
-printf("Hello, world!\n");
-}
+ void qmp_hello_world(Error **errp)
+ {
+ printf("Hello, world!\n");
+ }
 
 There are a few things to be noticed:
 
-1. QMP command implementatio