Peter Maydell <peter.mayd...@linaro.org> writes:
> Convert qemu-ga-ref to rST format. This includes dropping
> the plain-text, pdf and info format outputs for this document;
> as with all our other Sphinx-based documentation, we provide
> HTML and manpage only.
>
> The qemu-ga-ref.rst is somewhat more stripped down than
> the .texi was, because we do not (currently) attempt to
> generate indexes for the commands, events and data types
> being documented.
>
> As the GA ref is now part of the Sphinx 'interop' manual,
> we can delete the direct link from index.html.in.
>
> Reviewed-by: Richard Henderson <richard.hender...@linaro.org>
> Signed-off-by: Peter Maydell <peter.mayd...@linaro.org>
> ---
> docs/index.html.in | 1 -
> docs/interop/conf.py | 2 +
> docs/interop/index.rst | 1 +
> docs/interop/qemu-ga-ref.rst | 9 ++++
> docs/interop/qemu-ga-ref.texi | 80 -----------------------------------
> docs/meson.build | 1 +
> meson.build | 3 --
> MAINTAINERS | 2 +-
> qga/meson.build | 3 +-
> 9 files changed, 15 insertions(+), 87 deletions(-)
> create mode 100644 docs/interop/qemu-ga-ref.rst
> delete mode 100644 docs/interop/qemu-ga-ref.texi
>
> diff --git a/docs/index.html.in b/docs/index.html.in
> index ca28047881e..5b0f4e2bc2c 100644
> --- a/docs/index.html.in
> +++ b/docs/index.html.in
> @@ -13,7 +13,6 @@
> <li><a href="interop/index.html">System Emulation Management and
> Interoperability Guide</a></li>
> <li><a href="specs/index.html">System Emulation Guest Hardware
> Specifications</a></li>
> <li><a href="interop/qemu-qmp-ref.html">QMP Reference
> Manual</a></li>
> - <li><a href="interop/qemu-ga-ref.html">Guest Agent Protocol
> Reference</a></li>
> </ul>
> </body>
> </html>
> diff --git a/docs/interop/conf.py b/docs/interop/conf.py
> index 42ce7e3d365..e83632e0108 100644
> --- a/docs/interop/conf.py
> +++ b/docs/interop/conf.py
> @@ -19,4 +19,6 @@ html_theme_options['description'] = u'System Emulation
> Management and Interopera
> man_pages = [
> ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
> ['Michael Roth <mdr...@linux.vnet.ibm.com>'], 8),
> + ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference',
> + [], 7),
> ]
Why do you make the description a unicode legacy literal? I see it
matches existing entries. I'd like to know regardless :)
For what it's worth, the kernel's Documentation/conf.py uses a plain
string there.
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index 006f9864208..738cdbe185e 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -18,6 +18,7 @@ Contents:
> live-block-operations
> pr-helper
> qemu-ga
> + qemu-ga-ref
> vhost-user
> vhost-user-gpu
> vhost-vdpa
> diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst
> new file mode 100644
> index 00000000000..669019de71d
> --- /dev/null
> +++ b/docs/interop/qemu-ga-ref.rst
> @@ -0,0 +1,9 @@
> +QEMU Guest Agent Protocol Reference
> +===================================
> +
> +..
> + 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.
> +
> +.. qapi-doc:: qga/qapi-schema.json
> diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi
> deleted file mode 100644
> index a23cc2ed7f6..00000000000
> --- a/docs/interop/qemu-ga-ref.texi
> +++ /dev/null
> @@ -1,80 +0,0 @@
> -\input texinfo
> -@setfilename qemu-ga-ref.info
> -
> -@include version.texi
> -
> -@exampleindent 0
> -@paragraphindent 0
> -
> -@settitle QEMU Guest Agent Protocol Reference
> -
> -@iftex
> -@center @image{docs/qemu_logo}
> -@end iftex
> -
> -@copying
> -This is the QEMU Guest Agent Protocol reference manual.
> -
> -Copyright @copyright{} 2016 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-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference
> -@end direntry
> -
> -@titlepage
> -@title Guest Agent Protocol Reference Manual
> -@subtitle QEMU version @value{VERSION}
There is no obvious equivalent to @value{VERSION} in
docs/interop/qemu-ga-ref.rst.
The manual page generated from it has the version in the footer. Good.
I can't find it in the generated HTML. Not so good, but it wasn't there
before the patch, either.
The generated PDF had it on the title page.
Suggest to add a TODO comment like the one about the licensing
information.
> -@page
> -@vskip 0pt plus 1filll
> -@insertcopying
> -@end titlepage
> -
> -@contents
> -
> -@ifnottex
> -@node Top
> -@top QEMU Guest Agent protocol 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 qga/qga-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/docs/meson.build b/docs/meson.build
> index 50f367349b8..2569dd52ad6 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -15,6 +15,7 @@ if build_docs
> man_pages = {
> 'interop' : {
> 'qemu-ga.8': (have_tools ? 'man8' : ''),
> + 'qemu-ga-ref.7': 'man7',
> },
> 'tools': {
> 'qemu-img.1': (have_tools ? 'man1' : ''),
> diff --git a/meson.build b/meson.build
> index f4d1ab10968..c01c6230b3f 100644
> --- a/meson.build
> +++ b/meson.build
> @@ -1220,9 +1220,6 @@ if build_docs
> texi = {
> 'qemu-qmp-ref': ['docs/interop/qemu-qmp-ref.texi', qapi_doc_texi,
> version_texi],
> }
> - 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 makeinfo.found()
> cmd = [
> diff --git a/MAINTAINERS b/MAINTAINERS
> index dbddb0a7635..4b2705fc143 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2418,9 +2418,9 @@ M: Michael Roth <mdr...@linux.vnet.ibm.com>
> S: Maintained
> F: qga/
> F: docs/interop/qemu-ga.rst
> +F: docs/interop/qemu-ga-ref.rst
> F: scripts/qemu-guest-agent/
> F: tests/test-qga.c
> -F: docs/interop/qemu-ga-ref.texi
> T: git https://github.com/mdroth/qemu.git qga
>
> QOM
> diff --git a/qga/meson.build b/qga/meson.build
> index e5c5778a3e0..1c312b50cc9 100644
> --- a/qga/meson.build
> +++ b/qga/meson.build
> @@ -16,7 +16,7 @@ qga_qapi_outputs = [
> ]
>
> qga_qapi_files = custom_target('QGA QAPI files',
> - output: qga_qapi_outputs +
> ['qga-qapi-doc.texi'],
> + output: qga_qapi_outputs,
> input: 'qapi-schema.json',
> command: [ qapi_gen, '-o', 'qga', '-p',
> 'qga-', '@INPUT0@' ],
> depend_files: qapi_gen_depends)
> @@ -27,7 +27,6 @@ foreach output: qga_qapi_outputs
> qga_ss.add(qga_qapi_files[i])
> i = i + 1
> endforeach
> -qga_qapi_doc_texi = qga_qapi_files[i]
>
> qga_ss.add(files(
> 'commands.c',
