Re: [PATCH v6 09/21] docs/interop: Convert qemu-qmp-ref to rST

[Markus Armbruster]

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

> Convert qemu-qmp-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-qmp-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.
>
> Again, we drop the direct link from index.html.in now that
> the QMP ref is part of the interop manual.
>
> This commit removes the code from the root meson.build file that
> handled the various Texinfo-based outputs, because we no longer
> generate any documentation except for the Sphinx HTML manuals and the
> manpages, and the code can't handle having an empty list of files
> to process.. We'll do further cleanup of the remainders of

Extra period.

> Texinfo support in subsequent commits.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/index.html.in             |  1 -
>  docs/interop/conf.py           |  2 +
>  docs/interop/index.rst         |  1 +
>  docs/interop/qemu-qmp-ref.rst  |  9 ++++
>  docs/interop/qemu-qmp-ref.texi | 80 ---------------------------------
>  docs/meson.build               |  1 +
>  meson.build                    | 82 ----------------------------------
>  qapi/meson.build               |  4 +-
>  8 files changed, 14 insertions(+), 166 deletions(-)
>  create mode 100644 docs/interop/qemu-qmp-ref.rst
>  delete mode 100644 docs/interop/qemu-qmp-ref.texi
>
> diff --git a/docs/index.html.in b/docs/index.html.in
> index 5b0f4e2bc2c..33db4396ac8 100644
> --- a/docs/index.html.in
> +++ b/docs/index.html.in
> @@ -12,7 +12,6 @@
>              <li><a href="tools/index.html">Tools Guide</a></li>
>              <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>
>          </ul>
>      </body>
>  </html>
> diff --git a/docs/interop/conf.py b/docs/interop/conf.py
> index e83632e0108..43de386d33d 100644
> --- a/docs/interop/conf.py
> +++ b/docs/interop/conf.py
> @@ -21,4 +21,6 @@ man_pages = [
>       ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
>      ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference',
>       [], 7),
> +    ('qemu-qmp-ref', 'qemu-qmp-ref', u'QEMU QMP Reference Manual',
> +     [], 7),
>  ]
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index 738cdbe185e..cd78d679d82 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -19,6 +19,7 @@ Contents:
>     pr-helper
>     qemu-ga
>     qemu-ga-ref
> +   qemu-qmp-ref
>     vhost-user
>     vhost-user-gpu
>     vhost-vdpa
> diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst
> new file mode 100644
> index 00000000000..0c416fcaac2
> --- /dev/null
> +++ b/docs/interop/qemu-qmp-ref.rst
> @@ -0,0 +1,9 @@
> +QEMU 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.
> +
> +.. qapi-doc:: qapi/qapi-schema.json
> diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi
> deleted file mode 100644
> index ea1d7fe6c2d..00000000000
> --- a/docs/interop/qemu-qmp-ref.texi
> +++ /dev/null
> @@ -1,80 +0,0 @@
> -\input texinfo
> -@setfilename qemu-qmp-ref.info
> -
> -@include version.texi
> -
> -@exampleindent 0
> -@paragraphindent 0
> -
> -@settitle QEMU QMP Reference Manual
> -
> -@iftex
> -@center @image{docs/qemu_logo}
> -@end iftex
> -
> -@copying
> -This is the QEMU QMP 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-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual
> -@end direntry
> -
> -@titlepage
> -@title QMP Reference Manual
> -@subtitle QEMU version @value{VERSION}
> -@page
> -@vskip 0pt plus 1filll
> -@insertcopying
> -@end titlepage
> -
> -@contents
> -
> -@ifnottex
> -@node Top
> -@top QEMU 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 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/docs/meson.build b/docs/meson.build
> index 2569dd52ad6..69097e2ca07 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -16,6 +16,7 @@ if build_docs
>      'interop' : {
>          'qemu-ga.8': (have_tools ? 'man8' : ''),
>          'qemu-ga-ref.7': 'man7',
> +        'qemu-qmp-ref.7': 'man7',
>      },
>      'tools': {
>          'qemu-img.1': (have_tools ? 'man1' : ''),
> diff --git a/meson.build b/meson.build
> index c01c6230b3f..73d675ca834 100644
> --- a/meson.build
> +++ b/meson.build
> @@ -1203,88 +1203,6 @@ if 'CONFIG_GTK' in config_host
>    subdir('po')
>  endif
>  
> -if build_docs
> -  makeinfo = find_program('makeinfo', required: build_docs)
> -
> -  docs_inc = [
> -    '-I', meson.current_source_dir(),
> -    '-I', meson.current_build_dir() / 'docs',
> -    '-I', '@OUTDIR@',
> -  ]
> -
> -  version_texi = configure_file(output: 'version.texi',
> -                              input: 'version.texi.in',
> -                              configuration: {'VERSION': 
> meson.project_version(),
> -                                              'qemu_confdir': 
> config_host['qemu_confdir']})
> -
> -  texi = {
> -    'qemu-qmp-ref': ['docs/interop/qemu-qmp-ref.texi', qapi_doc_texi, 
> version_texi],
> -  }
> -
> -  if makeinfo.found()
> -    cmd = [
> -      'env', 'LC_ALL=C', makeinfo, '--no-split', '--number-sections', 
> docs_inc,
> -      '@INPUT0@', '-o', '@OUTPUT@',
> -    ]
> -    foreach ext, args: {
> -        'info': [],
> -        'html': ['--no-headers', '--html'],
> -        'txt': ['--no-headers', '--plaintext'],
> -    }
> -      t = []
> -      foreach doc, input: texi
> -        output = doc + '.' + ext
> -        t += custom_target(output,
> -                      input: input,
> -                      output: output,
> -                      install: true,
> -                      install_dir: qemu_docdir / 'interop',
> -                      command: cmd + args)
> -      endforeach
> -      alias_target(ext, t)
> -    endforeach
> -  endif
> -
> -  texi2pdf = find_program('texi2pdf', required: false)
> -
> -  if texi2pdf.found()
> -    pdfs = []
> -    foreach doc, input: texi
> -      output = doc + '.pdf'
> -      pdfs += custom_target(output,
> -                    input: input,
> -                    output: output,
> -                    command: [texi2pdf, '-q', docs_inc, '@INPUT0@', '-o', 
> '@OUTPUT@'],
> -                    build_by_default: false)
> -    endforeach
> -    alias_target('pdf', pdfs)
> -  endif
> -
> -  texi2pod = find_program('scripts/texi2pod.pl')
> -  pod2man = find_program('pod2man', required: build_docs)
> -
> -  if pod2man.found()
> -    foreach doc, input: texi
> -      man = doc + '.7'
> -      pod = custom_target(man + '.pod',
> -                          input: input,
> -                          output: man + '.pod',
> -                          command: [texi2pod,
> -                                    '-DVERSION="' + meson.project_version() 
> + '"',
> -                                    '-DCONFDIR="' + 
> config_host['qemu_confdir'] + '"',
> -                                    '@INPUT0@', '@OUTPUT@'])
> -      man = custom_target(man,
> -                          input: pod,
> -                          output: man,
> -                          capture: true,
> -                          install: true,
> -                          install_dir: get_option('mandir') / 'man7',
> -                          command: [pod2man, '--utf8', '--section=7', 
> '--center=" "',
> -                                    '--release=" "', '@INPUT@'])
> -    endforeach
> -  endif
> -endif
> -
>  if host_machine.system() == 'windows'
>    nsis_cmd = [
>      find_program('scripts/nsis.py'),
> diff --git a/qapi/meson.build b/qapi/meson.build
> index 2b2872a41d8..a287ca5d9d7 100644
> --- a/qapi/meson.build
> +++ b/qapi/meson.build
> @@ -97,7 +97,7 @@ foreach module : qapi_all_modules
>  endforeach
>  
>  qapi_files = custom_target('shared QAPI source files',
> -  output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs 
> + ['qapi-doc.texi'],
> +  output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs,
>    input: [ files('qapi-schema.json') ],
>    command: [ qapi_gen, '-o', 'qapi', '-b', '@INPUT0@' ],
>    depend_files: [ qapi_inputs, qapi_gen_depends ])
> @@ -121,5 +121,3 @@ foreach output : qapi_specific_outputs + 
> qapi_nonmodule_outputs
>    specific_ss.add(when: 'CONFIG_SOFTMMU', if_true: qapi_files[i])
>    i = i + 1
>  endforeach
> -
> -qapi_doc_texi = qapi_files[i]

Doesn't storage-daemon/qapi/meson.build need a similar update?

My comments on the previous patch apply.