[PATCH v3 0/3] docs: add qemu-storage-daemon documentation

[PATCH v3 0/3] docs: add qemu-storage-daemon documentation

[Stefan Hajnoczi]

v3:
 * Address Kevin's comments
v2:
 * Drop block-core.json h2 header removal, add an h1 header to
   storage-daemon/qapi/qapi-schema.json instead [Kevin]
 * Add Examples section to man page [Kevin]

Add documentation for the qemu-storage-daemon program and its QMP commands.

The man page looks like this:

QEMU-STORAGE-DAEMON(1)           QEMU           QEMU-STORAGE-DAEMON(1)

NAME
       qemu-storage-daemon - QEMU storage daemon

SYNOPSIS
       qemu-storage-daemon [options]

DESCRIPTION
       qemu-storage-daemon  provides  disk  image  functionality  from
       QEMU, qemu-img, and qemu-nbd in  a  long-running  process  con‐
       trolled  via QMP commands without running a virtual machine. It
       can export disk images, run block job operations,  and  perform
       other  disk-related  operations. The daemon is controlled via a
       QMP monitor and initial configuration from the command-line.

       The daemon offers the following subset of QEMU features:

       • Block nodes

       • Block jobs

       • Block exports

       • Throttle groups

       • Character devices

       • Crypto and secrets

       • QMP

       • IOThreads

       Commands can be sent over a QEMU Monitor Protocol (QMP) connec‐
       tion.  See the qemu-storage-daemon-qmp-ref(7) manual page for a
       description of the commands.

       The daemon runs until it is stopped using the quit QMP  command
       or SIGINT/SIGHUP/SIGTERM.

       Warning:  Never  modify  images in use by a running virtual ma‐
       chine or any other process; this may destroy the  image.  Also,
       be  aware  that querying an image that is being modified by an‐
       other process may encounter inconsistent state.

OPTIONS
       Standard options:

       -h, --help
              Display help and exit

       -V, --version
              Display version information and exit

       -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
              Specify tracing options.

              [enable=]PATTERN
                 Immediately enable events  matching  PATTERN  (either
                 event  name  or  a globbing pattern).  This option is
                 only available if QEMU has  been  compiled  with  the
                 simple,  log  or  ftrace tracing backend.  To specify
                 multiple events or patterns, specify the  -trace  op‐
                 tion multiple times.

                 Use  -trace  help  to  print a list of names of trace
                 points.

              events=FILE
                 Immediately enable events listed in FILE.   The  file
                 must  contain  one  event  name  (as  listed  in  the
                 trace-events-all file) per  line;  globbing  patterns
                 are  accepted  too.  This option is only available if
                 QEMU has been compiled with the simple, log or ftrace
                 tracing backend.

              file=FILE
                 Log  output  traces  to  FILE.   This  option is only
                 available if QEMU has been compiled with  the  simple
                 tracing backend.

       --blockdev BLOCKDEVDEF
              is  a block node definition. See the qemu(1) manual page
              for a description  of  block  node  properties  and  the
              qemu-block-drivers(7)  manual  page for a description of
              driver-specific parameters.

       --chardev CHARDEVDEF
              is a character device definition. See the qemu(1) manual
              page for a description of character device properties. A
              common character device definition configures a UNIX do‐
              main socket:

                 --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait

       --export    [type=]nbd,id=<id>,node-name=<node-name>[,name=<ex‐
       port-name>][,writable=on|off][,bitmap=<name>]

       --export
       [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,log‐
       ical-block-size=<block-size>][,num-queues=<num-queues>]

       --export
       [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,log‐
       ical-block-size=<block-size>][,num-queues=<num-queues>]
              is a block export definition.  node-name  is  the  block
              node   that  should  be  exported.  writable  determines
              whether or not the export allows write requests for mod‐
              ifying data (the default is off).

              The  nbd  export type requires --nbd-server (see below).
              name is the NBD export name. bitmap is  the  name  of  a
              dirty  bitmap  reachable from the block node, so the NBD
              client can use NBD_OPT_SET_META_CONTEXT with  the  meta‐
              data  context name "qemu:dirty-bitmap:BITMAP" to inspect
              the bitmap.

              The vhost-user-blk export type takes a vhost-user socket
              address  on  which  it accept incoming connections. Both
              addr.type=unix,addr.path=<socket-path> for  UNIX  domain
              sockets and addr.type=fd,addr.str=<fd> for file descrip‐
              tor passing are supported.  logical-block-size sets  the
              logical  block  size  in  bytes  (the  default  is 512).
              num-queues sets the number of virtqueues (the default is
              1).

       --monitor MONITORDEF
              is a QMP monitor definition. See the qemu(1) manual page
              for a description of QMP monitor  properties.  A  common
              QMP monitor definition configures a monitor on character
              device char1:

                 --monitor chardev=char1

       --nbd-server
       addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐
       thz=<id>][,max-connections=<n>]

       --nbd-server
       addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐
       thz=<id>][,max-connections=<n>]
              is a server for NBD exports. Both TCP  and  UNIX  domain
              sockets are supported.  TLS encryption can be configured
              using --object tls-creds-* and authz-* secrets (see  be‐
              low).

              To  configure  an  NBD server on UNIX domain socket path
              /tmp/nbd.sock:

                 --nbd-server addr.type=unix,addr.path=/tmp/nbd.sock

       --object help

       --object <type>,help

       --object <type>[,<property>=<value>...]
              is a QEMU user creatable object definition. List  object
              types   with   help.    List   object   properties  with
              <type>,help. See the qemu(1) manual page for a  descrip‐
              tion of the object properties.

EXAMPLES
       Launch  the  daemon with QMP monitor socket qmp.sock so clients
       can execute QMP commands:

          $ qemu-storage-daemon \
              --chardev socket,path=qmp.sock,server,nowait,id=char1 \
              --monitor chardev=char1

       Export raw image file disk.img  over  NBD  UNIX  domain  socket
       nbd.sock:

          $ qemu-storage-daemon \
              --blockdev driver=file,node-name=disk,filename=disk.img \
              --nbd-server addr.type=unix,addr.path=nbd.sock \
              --export type=nbd,id=export,node-name=disk,writable=on

       Export  a  qcow2 image file disk.qcow2 as a vhosts-user-blk de‐
       vice over UNIX domain socket vhost-user-blk.sock:

          $ qemu-storage-daemon \
              --blockdev driver=file,node-name=file,filename=disk.qcow2 \
              --blockdev driver=qcow2,node-name=qcow2,file=file \
              --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2

SEE ALSO
       qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)

COPYRIGHT
       2020, The QEMU Project Developers

5.1.94                       Dec 09, 2020       QEMU-STORAGE-DAEMON(1)

Stefan Hajnoczi (3):
  docs: generate qemu-storage-daemon-qmp-ref(7) man page
  docs: add qemu-storage-daemon(1) man page
  MAINTAINERS: add Kevin Wolf as storage daemon maintainer

 MAINTAINERS                                  |   9 ++
 docs/interop/index.rst                       |   1 +
 docs/interop/qemu-storage-daemon-qmp-ref.rst |  13 ++
 docs/tools/index.rst                         |   1 +
 docs/tools/qemu-storage-daemon.rst           | 148 +++++++++++++++++++
 storage-daemon/qapi/qapi-schema.json         |   3 +
 docs/interop/conf.py                         |   2 +
 docs/meson.build                             |   1 +
 docs/tools/conf.py                           |   2 +
 9 files changed, 180 insertions(+)
 create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst
 create mode 100644 docs/tools/qemu-storage-daemon.rst

-- 
2.28.0

[PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

[Stefan Hajnoczi]

Although individual qemu-storage-daemon QMP commands are identical to
QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's
QMP commands. Generate a manual page of just the commands supported by
qemu-storage-daemon so that users know exactly what is available in
qemu-storage-daemon.

Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
block-core.json is at the h2 heading level.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/interop/index.rst                       |  1 +
 docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 +++++++++++++
 storage-daemon/qapi/qapi-schema.json         |  3 +++
 docs/interop/conf.py                         |  2 ++
 docs/meson.build                             |  1 +
 5 files changed, 20 insertions(+)
 create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst

diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index cd78d679d8..95d56495f6 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -20,6 +20,7 @@ Contents:
    qemu-ga
    qemu-ga-ref
    qemu-qmp-ref
+   qemu-storage-daemon-qmp-ref
    vhost-user
    vhost-user-gpu
    vhost-vdpa
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
new file mode 100644
index 0000000000..caf9dad23a
--- /dev/null
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
@@ -0,0 +1,13 @@
+QEMU Storage Daemon QMP Reference Manual
+========================================
+
+..
+   TODO: the old Texinfo manual used to note that this manual
+   is GPL-v2-or-later. We should make that reader-visible
+   both here and in our Sphinx manuals more generally.
+
+..
+   TODO: display the QEMU version, both here and in our Sphinx manuals
+   more generally.
+
+.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
index c6ad5ae1e3..28117c3aac 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -15,6 +15,9 @@
 
 { 'include': '../../qapi/pragma.json' }
 
+##
+# = Block devices
+##
 { 'include': '../../qapi/block-core.json' }
 { 'include': '../../qapi/block-export.json' }
 { 'include': '../../qapi/char.json' }
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 2634ca3410..f4370aaa13 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -23,4 +23,6 @@ man_pages = [
      [], 7),
     ('qemu-qmp-ref', 'qemu-qmp-ref', 'QEMU QMP Reference Manual',
      [], 7),
+    ('qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref',
+     'QEMU Storage Daemon QMP Reference Manual', [], 7),
 ]
diff --git a/docs/meson.build b/docs/meson.build
index ebd85d59f9..df5dc50485 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -56,6 +56,7 @@ if build_docs
         'qemu-ga.8': (have_tools ? 'man8' : ''),
         'qemu-ga-ref.7': 'man7',
         'qemu-qmp-ref.7': 'man7',
+        'qemu-storage-daemon-qmp-ref.7': (have_tools ? 'man7' : ''),
     },
     'tools': {
         'qemu-img.1': (have_tools ? 'man1' : ''),
-- 
2.28.0

[PATCH v3 2/3] docs: add qemu-storage-daemon(1) man page

[Stefan Hajnoczi]

Document the qemu-storage-daemon tool. Most of the command-line options
are identical to their QEMU counterparts. Perhaps Sphinx hxtool
integration could be extended to extract documentation for individual
command-line options so they can be shared. For now the
qemu-storage-daemon simply refers to the qemu(1) man page where the
command-line options are identical.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/tools/index.rst               |   1 +
 docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++++++++++++
 docs/tools/conf.py                 |   2 +
 3 files changed, 151 insertions(+)
 create mode 100644 docs/tools/qemu-storage-daemon.rst

diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index b99f86c7c6..3a5829c17a 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -11,6 +11,7 @@ Contents:
    :maxdepth: 2
 
    qemu-img
+   qemu-storage-daemon
    qemu-nbd
    qemu-pr-helper
    qemu-trace-stap
diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
new file mode 100644
index 0000000000..f63627eaf6
--- /dev/null
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -0,0 +1,148 @@
+QEMU Storage Daemon
+===================
+
+Synopsis
+--------
+
+**qemu-storage-daemon** [options]
+
+Description
+-----------
+
+qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
+qemu-nbd in a long-running process controlled via QMP commands without running
+a virtual machine. It can export disk images, run block job operations, and
+perform other disk-related operations. The daemon is controlled via a QMP
+monitor and initial configuration from the command-line.
+
+The daemon offers the following subset of QEMU features:
+
+* Block nodes
+* Block jobs
+* Block exports
+* Throttle groups
+* Character devices
+* Crypto and secrets
+* QMP
+* IOThreads
+
+Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
+:manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
+commands.
+
+The daemon runs until it is stopped using the ``quit`` QMP command or
+SIGINT/SIGHUP/SIGTERM.
+
+**Warning:** Never modify images in use by a running virtual machine or any
+other process; this may destroy the image. Also, be aware that querying an
+image that is being modified by another process may encounter inconsistent
+state.
+
+Options
+-------
+
+.. program:: qemu-storage-daemon
+
+Standard options:
+
+.. option:: -h, --help
+
+  Display help and exit
+
+.. option:: -V, --version
+
+  Display version information and exit
+
+.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
+
+  .. include:: ../qemu-option-trace.rst.inc
+
+.. option:: --blockdev BLOCKDEVDEF
+
+  is a block node definition. See the :manpage:`qemu(1)` manual page for a
+  description of block node properties and the :manpage:`qemu-block-drivers(7)`
+  manual page for a description of driver-specific parameters.
+
+.. option:: --chardev CHARDEVDEF
+
+  is a character device definition. See the :manpage:`qemu(1)` manual page for
+  a description of character device properties. A common character device
+  definition configures a UNIX domain socket::
+
+  --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
+
+.. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
+  --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
+  --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
+
+  is a block export definition. ``node-name`` is the block node that should be
+  exported. ``writable`` determines whether or not the export allows write
+  requests for modifying data (the default is off).
+
+  The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
+  the NBD export name. ``bitmap`` is the name of a dirty bitmap reachable from
+  the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
+  metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
+
+  The ``vhost-user-blk`` export type takes a vhost-user socket address on which
+  it accept incoming connections. Both
+  ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
+  ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
+  ``logical-block-size`` sets the logical block size in bytes (the default is
+  512). ``num-queues`` sets the number of virtqueues (the default is 1).
+
+.. option:: --monitor MONITORDEF
+
+  is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
+  a description of QMP monitor properties. A common QMP monitor definition
+  configures a monitor on character device ``char1``::
+
+  --monitor chardev=char1
+
+.. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
+  --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
+
+  is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
+  TLS encryption can be configured using ``--object`` tls-creds-* and authz-*
+  secrets (see below).
+
+  To configure an NBD server on UNIX domain socket path ``/tmp/nbd.sock``::
+
+  --nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
+
+.. option:: --object help
+  --object <type>,help
+  --object <type>[,<property>=<value>...]
+
+  is a QEMU user creatable object definition. List object types with ``help``.
+  List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
+  manual page for a description of the object properties.
+
+Examples
+--------
+Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
+QMP commands::
+
+  $ qemu-storage-daemon \
+      --chardev socket,path=qmp.sock,server,nowait,id=char1 \
+      --monitor chardev=char1
+
+Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
+
+  $ qemu-storage-daemon \
+      --blockdev driver=file,node-name=disk,filename=disk.img \
+      --nbd-server addr.type=unix,addr.path=nbd.sock \
+      --export type=nbd,id=export,node-name=disk,writable=on
+
+Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
+domain socket ``vhost-user-blk.sock``::
+
+  $ qemu-storage-daemon \
+      --blockdev driver=file,node-name=file,filename=disk.qcow2 \
+      --blockdev driver=qcow2,node-name=qcow2,file=file \
+      --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
+
+See also
+--------
+
+:manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 4760d36ff2..7072d99324 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -20,6 +20,8 @@ html_theme_options['description'] = \
 man_pages = [
     ('qemu-img', 'qemu-img', u'QEMU disk image utility',
      ['Fabrice Bellard'], 1),
+    ('qemu-storage-daemon', 'qemu-storage-daemon', u'QEMU storage daemon',
+     [], 1),
     ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
      ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
     ('qemu-pr-helper', 'qemu-pr-helper', 'QEMU persistent reservation helper',
-- 
2.28.0

[PATCH v3 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer

[Stefan Hajnoczi]

The MAINTAINERS file was not updated when the storage daemon was merged.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Acked-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
---
 MAINTAINERS | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 68bc160f41..8676730cc9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2146,6 +2146,15 @@ F: qobject/block-qdict.c
 F: tests/check-block-qdict.c
 T: git https://repo.or.cz/qemu/kevin.git block
 
+Storage daemon
+M: Kevin Wolf <kwolf@redhat.com>
+L: qemu-block@nongnu.org
+S: Supported
+F: storage-daemon/
+F: docs/interop/qemu-storage-daemon-qmp-ref.rst
+F: docs/tools/qemu-storage-daemon.rst
+T: git https://repo.or.cz/qemu/kevin.git block
+
 Block I/O path
 M: Stefan Hajnoczi <stefanha@redhat.com>
 M: Fam Zheng <fam@euphon.net>
-- 
2.28.0

Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

[Kevin Wolf]

Am 09.12.2020 um 11:38 hat Stefan Hajnoczi geschrieben:
> Although individual qemu-storage-daemon QMP commands are identical to
> QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's
> QMP commands. Generate a manual page of just the commands supported by
> qemu-storage-daemon so that users know exactly what is available in
> qemu-storage-daemon.
> 
> Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
> block-core.json is at the h2 heading level.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/interop/index.rst                       |  1 +
>  docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 +++++++++++++
>  storage-daemon/qapi/qapi-schema.json         |  3 +++
>  docs/interop/conf.py                         |  2 ++
>  docs/meson.build                             |  1 +
>  5 files changed, 20 insertions(+)
>  create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst
> 
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index cd78d679d8..95d56495f6 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -20,6 +20,7 @@ Contents:
>     qemu-ga
>     qemu-ga-ref
>     qemu-qmp-ref
> +   qemu-storage-daemon-qmp-ref
>     vhost-user
>     vhost-user-gpu
>     vhost-vdpa
> diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> new file mode 100644
> index 0000000000..caf9dad23a
> --- /dev/null
> +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> @@ -0,0 +1,13 @@
> +QEMU Storage Daemon QMP Reference Manual
> +========================================
> +
> +..
> +   TODO: the old Texinfo manual used to note that this manual
> +   is GPL-v2-or-later. We should make that reader-visible
> +   both here and in our Sphinx manuals more generally.
> +
> +..
> +   TODO: display the QEMU version, both here and in our Sphinx manuals
> +   more generally.
> +
> +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json

Did you intend to actually merge the TODO comments like this into master
or was this meant to be resolved before you send the series?

Kevin

Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1210 bytes --]

On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > new file mode 100644
> > index 0000000000..caf9dad23a
> > --- /dev/null
> > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > @@ -0,0 +1,13 @@
> > +QEMU Storage Daemon QMP Reference Manual
> > +========================================
> > +
> > +..
> > +   TODO: the old Texinfo manual used to note that this manual
> > +   is GPL-v2-or-later. We should make that reader-visible
> > +   both here and in our Sphinx manuals more generally.
> > +
> > +..
> > +   TODO: display the QEMU version, both here and in our Sphinx manuals
> > +   more generally.
> > +
> > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> 
> Did you intend to actually merge the TODO comments like this into master
> or was this meant to be resolved before you send the series?

Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
have these comments and I copied them when creating the file. I don't
intend to try to solve that in this series.

Would you like to keep the comments or should I drop them?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

[Peter Maydell]

On Wed, 16 Dec 2020 at 16:21, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > new file mode 100644
> > > index 0000000000..caf9dad23a
> > > --- /dev/null
> > > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > @@ -0,0 +1,13 @@
> > > +QEMU Storage Daemon QMP Reference Manual
> > > +========================================
> > > +
> > > +..
> > > +   TODO: the old Texinfo manual used to note that this manual
> > > +   is GPL-v2-or-later. We should make that reader-visible
> > > +   both here and in our Sphinx manuals more generally.
> > > +
> > > +..
> > > +   TODO: display the QEMU version, both here and in our Sphinx manuals
> > > +   more generally.
> > > +
> > > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> >
> > Did you intend to actually merge the TODO comments like this into master
> > or was this meant to be resolved before you send the series?
>
> Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
> have these comments and I copied them when creating the file. I don't
> intend to try to solve that in this series.
>
> Would you like to keep the comments or should I drop them?

FWIW, the ones in those two docs are the result of a request
from Markus when we were doing the conversion of QAPI generated
docs from Texinfo to rST -- the old separate Texinfo-generated
docs ended up with a version/license statement in the generated
docs. Fixing this depends I think on the "merge the 5 manuals
into one single manual" patch; once that's done then it should
be easier to have one consistent place to note license, copyright,
version, etc.

thanks
-- PMM

Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

[Kevin Wolf]

[-- Attachment #1: Type: text/plain, Size: 1430 bytes --]

Am 16.12.2020 um 17:21 hat Stefan Hajnoczi geschrieben:
> On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > new file mode 100644
> > > index 0000000000..caf9dad23a
> > > --- /dev/null
> > > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > @@ -0,0 +1,13 @@
> > > +QEMU Storage Daemon QMP Reference Manual
> > > +========================================
> > > +
> > > +..
> > > +   TODO: the old Texinfo manual used to note that this manual
> > > +   is GPL-v2-or-later. We should make that reader-visible
> > > +   both here and in our Sphinx manuals more generally.
> > > +
> > > +..
> > > +   TODO: display the QEMU version, both here and in our Sphinx manuals
> > > +   more generally.
> > > +
> > > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> > 
> > Did you intend to actually merge the TODO comments like this into master
> > or was this meant to be resolved before you send the series?
> 
> Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
> have these comments and I copied them when creating the file. I don't
> intend to try to solve that in this series.
> 
> Would you like to keep the comments or should I drop them?

Ah, I see. If the same already exists in other places, I'll just merge
it as it is. Thanks!

Kevin

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1576 bytes --]

On Wed, Dec 16, 2020 at 06:59:03PM +0100, Kevin Wolf wrote:
> Am 16.12.2020 um 17:21 hat Stefan Hajnoczi geschrieben:
> > On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > > > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > > new file mode 100644
> > > > index 0000000000..caf9dad23a
> > > > --- /dev/null
> > > > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > > @@ -0,0 +1,13 @@
> > > > +QEMU Storage Daemon QMP Reference Manual
> > > > +========================================
> > > > +
> > > > +..
> > > > +   TODO: the old Texinfo manual used to note that this manual
> > > > +   is GPL-v2-or-later. We should make that reader-visible
> > > > +   both here and in our Sphinx manuals more generally.
> > > > +
> > > > +..
> > > > +   TODO: display the QEMU version, both here and in our Sphinx manuals
> > > > +   more generally.
> > > > +
> > > > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> > > 
> > > Did you intend to actually merge the TODO comments like this into master
> > > or was this meant to be resolved before you send the series?
> > 
> > Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
> > have these comments and I copied them when creating the file. I don't
> > intend to try to solve that in this series.
> > 
> > Would you like to keep the comments or should I drop them?
> 
> Ah, I see. If the same already exists in other places, I'll just merge
> it as it is. Thanks!

Great, thanks!

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]