diff mbox series

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

Message ID 20200910144400.69615-2-stefanha@redhat.com (mailing list archive)
State New, archived
Headers show
Series docs: add qemu-storage-daemon documentation | expand

Commit Message

Stefan Hajnoczi Sept. 10, 2020, 2:43 p.m. UTC 
Although qemu-storage-daemon QMP commands are identical to QEMU QMP
commands they are a subset. 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>
---
 storage-daemon/qapi/qapi-schema.json          |  4 +
 docs/interop/qemu-storage-daemon-qmp-ref.texi | 80 +++++++++++++++++++
 meson.build                                   |  9 +++
 storage-daemon/qapi/meson.build               |  2 +
 4 files changed, 95 insertions(+)
 create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.texi

Comments

Kevin Wolf Oct. 6, 2020, 10:22 a.m. UTC | #1 
Am 10.09.2020 um 16:43 hat Stefan Hajnoczi geschrieben:
> Although qemu-storage-daemon QMP commands are identical to QEMU QMP
> commands they are a subset. 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>

As the series doesn't apply any more, I can't actually try it out
easily, but is the order of includes in the schema right now?

I seem to remember that in v1 we discussed that nested includes result
in an unexpected section structure in the documentation in some cases
(such as generic jobs being documented in a subsection of block
devices), and that we need to reorder includes in qapi-schema.json to
fix this because a more clever doc generator wasn't considered worth the
effort.

Kevin
Stefan Hajnoczi Dec. 9, 2020, 10:21 a.m. UTC | #2 
On Tue, Oct 06, 2020 at 12:22:55PM +0200, Kevin Wolf wrote:
> Am 10.09.2020 um 16:43 hat Stefan Hajnoczi geschrieben:
> > Although qemu-storage-daemon QMP commands are identical to QEMU QMP
> > commands they are a subset. 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>
> 
> As the series doesn't apply any more, I can't actually try it out
> easily, but is the order of includes in the schema right now?
> 
> I seem to remember that in v1 we discussed that nested includes result
> in an unexpected section structure in the documentation in some cases
> (such as generic jobs being documented in a subsection of block
> devices), and that we need to reorder includes in qapi-schema.json to
> fix this because a more clever doc generator wasn't considered worth the
> effort.

v2 onwards takes a different approach and leaves the header where it is.

Stefan
diff mbox series

Patch

diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
index 6100d1f0c9..939a6afd18 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -15,7 +15,11 @@ 
 
 { 'include': '../../qapi/pragma.json' }
 
+##
+# = Block devices
+##
 { 'include': '../../qapi/block-core.json' }
+
 { 'include': '../../qapi/char.json' }
 { 'include': '../../qapi/common.json' }
 { 'include': '../../qapi/control.json' }
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.texi b/docs/interop/qemu-storage-daemon-qmp-ref.texi
new file mode 100644
index 0000000000..a6a70c9674
--- /dev/null
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.texi
@@ -0,0 +1,80 @@ 
+\input texinfo
+@setfilename qemu-storage-daemon-qmp-ref.info
+
+@include version.texi
+
+@exampleindent 0
+@paragraphindent 0
+
+@settitle QEMU Storage Daemon QMP Reference Manual
+
+@iftex
+@center @image{docs/qemu_logo}
+@end iftex
+
+@copying
+This is the QEMU Storage Daemon QMP reference manual.
+
+Copyright @copyright{} 2020 The QEMU Project developers
+
+@quotation
+This manual is free documentation: you can redistribute it and/or
+modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation, either version 2 of the
+License, or (at your option) any later version.
+
+This manual is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this manual.  If not, see http://www.gnu.org/licenses/.
+@end quotation
+@end copying
+
+@dircategory QEMU
+@direntry
+* QEMU-Storage-Daemon-QMP-Ref: (qemu-storage-daemon-qmp-ref). QEMU Storage Daemon QMP Reference Manual
+@end direntry
+
+@titlepage
+@title QEMU Storage Daemon QMP Reference Manual
+@subtitle QEMU version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top QEMU Storage Daemon QMP reference
+@end ifnottex
+
+@menu
+* API Reference::
+* Commands and Events Index::
+* Data Types Index::
+@end menu
+
+@node API Reference
+@chapter API Reference
+
+@c for texi2pod:
+@c man begin DESCRIPTION
+
+@include storage-daemon/qapi/qapi-doc.texi
+
+@c man end
+
+@node Commands and Events Index
+@unnumbered Commands and Events Index
+@printindex fn
+
+@node Data Types Index
+@unnumbered Data Types Index
+@printindex tp
+
+@bye
diff --git a/meson.build b/meson.build
index 5421eca66a..f20e409f8e 100644
--- a/meson.build
+++ b/meson.build
@@ -1229,6 +1229,15 @@  if build_docs
   if 'CONFIG_GUEST_AGENT' in config_host
     texi += {'qemu-ga-ref': ['docs/interop/qemu-ga-ref.texi', qga_qapi_doc_texi, version_texi]}
   endif
+  if have_tools
+    texi += {
+      'qemu-storage-daemon-qmp-ref': [
+	'docs/interop/qemu-storage-daemon-qmp-ref.texi',
+	qsd_qapi_doc_texi,
+	version_texi
+      ]
+    }
+  endif
 
   if makeinfo.found()
     cmd = [
diff --git a/storage-daemon/qapi/meson.build b/storage-daemon/qapi/meson.build
index cea618bec0..7c48a388d4 100644
--- a/storage-daemon/qapi/meson.build
+++ b/storage-daemon/qapi/meson.build
@@ -4,4 +4,6 @@  qsd_qapi_files = custom_target('QAPI files for qemu-storage-daemon',
                                command: [ qapi_gen, '-o', 'storage-daemon/qapi', '@INPUT@' ],
                                depend_files: [ qapi_inputs, qapi_gen_depends ])
 
+qsd_qapi_doc_texi = qsd_qapi_files[-1]
+
 qsd_ss.add(qsd_qapi_files.to_list())