Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-09-29' into staging

QAPI patches patches for 2020-09-29

# gpg: Signature made Tue 29 Sep 2020 20:54:51 BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2020-09-29: (29 commits)
  Remove texinfo dependency from docker and CI configs
  configure: Drop texinfo requirement
  Remove Texinfo related line from git.orderfile
  scripts/texi2pod: Delete unused script
  docs/devel/qapi-code-gen.txt: Update to new rST backend conventions
  scripts/qapi: Remove texinfo generation support
  tests/qapi-schema: Add test of the rST QAPI doc-comment output
  meson.build: Make manuals depend on source to Sphinx extensions
  meson.build: Move SPHINX_ARGS to top level meson.build file
  tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis
  qga/qapi-schema.json: Add some headings
  qapi: Use rST markup for literal blocks
  docs/interop: Convert qemu-qmp-ref to rST
  docs/interop: Convert qemu-ga-ref to rST
  docs/sphinx: Add new qapi-doc Sphinx extension
  qapi/machine.json: Escape a literal '*' in doc comment
  scripts/qapi/parser.py: improve doc comment indent handling
  scripts/qapi: Move doc-comment whitespace stripping to doc.py
  tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension
  qapi/block.json: Add newline after "Example:" for block-latency-histogram-set
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell
2020-09-29 23:19:39 +01:00
71 changed files with 2113 additions and 2449 deletions
-1
View File
@@ -192,7 +192,6 @@ jobs:
apt:
packages:
- python3-sphinx
- texinfo
- perl
+5 -1
View File
@@ -1617,6 +1617,7 @@ F: include/hw/pci/*
F: hw/misc/pci-testdev.c
F: hw/pci/*
F: hw/pci-bridge/*
F: qapi/pci.json
F: docs/pci*
F: docs/specs/*pci*
F: default-configs/pci.mak
@@ -1632,6 +1633,7 @@ F: hw/acpi/*
F: hw/smbios/*
F: hw/i386/acpi-build.[hc]
F: hw/arm/virt-acpi-build.c
F: qapi/acpi.json
F: tests/qtest/bios-tables-test*
F: tests/qtest/acpi-utils.[hc]
F: tests/data/acpi/
@@ -2385,6 +2387,7 @@ F: tests/test-qmp-*.c
F: tests/test-visitor-serialization.c
F: scripts/qapi-gen.py
F: scripts/qapi/*
F: docs/sphinx/qapidoc.py
F: docs/devel/qapi*
T: git https://repo.or.cz/qemu/armbru.git qapi-next
@@ -2418,9 +2421,9 @@ M: Michael Roth <mdroth@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
@@ -3149,6 +3152,7 @@ M: Peter Maydell <peter.maydell@linaro.org>
S: Maintained
F: docs/conf.py
F: docs/*/conf.py
F: docs/sphinx/
Miscellaneous
-------------
+1 -1
View File
@@ -280,7 +280,7 @@ endif
$(call print-help,vm-help,Help about targets running tests inside VM)
@echo ''
@echo 'Documentation targets:'
$(call print-help,html info pdf txt man,Build documentation in specified format)
$(call print-help,html man,Build documentation in specified format)
@echo ''
ifdef CONFIG_WIN32
@echo 'Windows targets:'
+1 -1
View File
@@ -42,7 +42,7 @@
#include "qemu/uuid.h"
#include "sysemu/replay.h"
#include "qapi/error.h"
#include "qapi/qapi-commands-misc.h"
#include "qapi/qapi-commands-machine.h"
#include "qapi/qmp/qdict.h"
#include "qapi/qmp/qstring.h"
#include "crypto/secret.h"
Vendored
+2 -10
View File
@@ -4874,14 +4874,14 @@ if test "$docs" != "no" ; then
else
sphinx_ok=no
fi
if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then
if test "$sphinx_ok" = "yes"; then
docs=yes
else
if test "$docs" = "yes" ; then
if has $sphinx_build && test "$sphinx_ok" != "yes"; then
echo "Warning: $sphinx_build exists but it is either too old or uses too old a Python version" >&2
fi
feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx"
feature_not_found "docs" "Install a Python 3 version of python-sphinx"
fi
docs=no
fi
@@ -6301,13 +6301,6 @@ if test "$solaris" = "no" && test "$tsan" = "no"; then
fi
fi
# test if pod2man has --utf8 option
if pod2man --help | grep -q utf8; then
POD2MAN="pod2man --utf8"
else
POD2MAN="pod2man"
fi
# Use ASLR, no-SEH and DEP if available
if test "$mingw32" = "yes" ; then
for flag in --dynamicbase --no-seh --nxcompat; do
@@ -7456,7 +7449,6 @@ echo "HOST_DSOSUF=$HOST_DSOSUF" >> $config_host_mak
echo "LIBS_QGA=$libs_qga" >> $config_host_mak
echo "TASN1_LIBS=$tasn1_libs" >> $config_host_mak
echo "TASN1_CFLAGS=$tasn1_cflags" >> $config_host_mak
echo "POD2MAN=$POD2MAN" >> $config_host_mak
if test "$gcov" = "yes" ; then
echo "CONFIG_GCOV=y" >> $config_host_mak
fi
+5 -1
View File
@@ -52,7 +52,10 @@ except NameError:
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use an absolute path starting from qemu_docdir.
#
# Our extensions are in docs/sphinx; the qapidoc extension requires
# the QAPI modules from scripts/.
sys.path.insert(0, os.path.join(qemu_docdir, "sphinx"))
sys.path.insert(0, os.path.join(qemu_docdir, "../scripts"))
# -- General configuration ------------------------------------------------
@@ -67,7 +70,7 @@ needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile']
extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -241,3 +244,4 @@ texinfo_documents = [
kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc')
kerneldoc_srctree = os.path.join(qemu_docdir, '..')
hxtool_srctree = os.path.join(qemu_docdir, '..')
qapidoc_srctree = os.path.join(qemu_docdir, '..')
+76 -30
View File
@@ -824,23 +824,37 @@ See below for more on definition documentation.
Free-form documentation may be used to provide additional text and
structuring content.
==== Headings and subheadings ====
A free-form documentation comment containing a line which starts with
some '=' symbols and then a space defines a section heading:
##
# = This is a top level heading
#
# This is a free-form comment which will go under the
# top level heading.
##
##
# == This is a second level heading
##
A heading line must be the first line of the documentation
comment block.
Section headings must always be correctly nested, so you can only
define a third-level heading inside a second-level heading, and so on.
==== Documentation markup ====
Comment text starting with '=' is a section title:
Documentation comments can use most rST markup. In particular,
a '::' literal block can be used for examples:
# = Section title
Double the '=' for a subsection title:
# == Subsection title
Both are only permitted in free-form documentation.
'|' denotes examples:
# | Text of the example, may span
# | multiple lines
# ::
#
# Text of the example, may span
# multiple lines
'*' starts an itemized list:
@@ -856,34 +870,33 @@ A decimal number followed by '.' starts a numbered list:
# multiple lines
# 2. Second item
The actual number doesn't matter. You could even use '*' instead of
'2.' for the second item.
The actual number doesn't matter.
Lists can't be nested. Blank lines are currently not supported within
lists.
Lists of either kind must be preceded and followed by a blank line.
If a list item's text spans multiple lines, then the second and
subsequent lines must be correctly indented to line up with the
first character of the first line.
Additional whitespace between the initial '#' and the comment text is
permitted.
*foo* and _foo_ are for strong and emphasis styles respectively (they
do not work over multiple lines). @foo is used to reference a name in
the schema.
The usual '**strong**', '*emphasised*' and '``literal``' markup should
be used. If you need a single literal '*' you will need to
backslash-escape it. As an extension beyond the usual rST syntax, you
can also use '@foo' to reference a name in the schema; this is
rendered the same way as '``foo``'.
Example:
##
# = Section
# == Subsection
#
# Some text foo with *strong* and _emphasis_
# Some text foo with **bold** and *emphasis*
# 1. with a list
# 2. like that
#
# And some code:
# | $ echo foo
# | -> do this
# | <- get that
#
# ::
#
# $ echo foo
# -> do this
# <- get that
##
@@ -901,6 +914,22 @@ commands and events), member (for structs and unions), branch (for
alternates), or value (for enums), and finally optional tagged
sections.
Descriptions of arguments can span multiple lines. The description
text can start on the line following the '@argname:', in which case it
must not be indented at all. It can also start on the same line as
the '@argname:'. In this case if it spans multiple lines then second
and subsequent lines must be indented to line up with the first
character of the first line of the description:
# @argone:
# This is a two line description
# in the first style.
#
# @argtwo: This is a two line description
# in the second style.
The number of spaces between the ':' and the text is not significant.
FIXME: the parser accepts these things in almost any order.
FIXME: union branches should be described, too.
@@ -911,9 +940,26 @@ A tagged section starts with one of the following words:
"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
The section ends with the start of a new section.
The text of a section can start on a new line, in
which case it must not be indented at all. It can also start
on the same line as the 'Note:', 'Returns:', etc tag. In this
case if it spans multiple lines then second and subsequent
lines must be indented to match the first, in the same way as
multiline argument descriptions.
A 'Since: x.y.z' tagged section lists the release that introduced the
definition.
The text of a section can start on a new line, in
which case it must not be indented at all. It can also start
on the same line as the 'Note:', 'Returns:', etc tag. In this
case if it spans multiple lines then second and subsequent
lines must be indented to match the first.
An 'Example' or 'Examples' section is automatically rendered
entirely as literal fixed-width text. In other sections,
the text is formatted, and rST markup can be used.
For example:
##
-2
View File
@@ -12,8 +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>
<li><a href="interop/qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>
</ul>
</body>
</html>
+4
View File
@@ -19,4 +19,8 @@ html_theme_options['description'] = u'System Emulation Management and Interopera
man_pages = [
('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
('qemu-ga-ref', 'qemu-ga-ref', 'QEMU Guest Agent Protocol Reference',
[], 7),
('qemu-qmp-ref', 'qemu-qmp-ref', 'QEMU QMP Reference Manual',
[], 7),
]
+2
View File
@@ -18,6 +18,8 @@ Contents:
live-block-operations
pr-helper
qemu-ga
qemu-ga-ref
qemu-qmp-ref
vhost-user
vhost-user-gpu
vhost-vdpa
+13
View File
@@ -0,0 +1,13 @@
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.
..
TODO: display the QEMU version, both here and in our Sphinx manuals
more generally.
.. qapi-doc:: qga/qapi-schema.json
-80
View File
@@ -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}
@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
+13
View File
@@ -0,0 +1,13 @@
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.
..
TODO: display the QEMU version, both here and in our Sphinx manuals
more generally.
.. qapi-doc:: qapi/qapi-schema.json
-80
View File
@@ -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
+4 -8
View File
@@ -1,11 +1,3 @@
SPHINX_ARGS = [config_host['SPHINX_BUILD'],
'-Dversion=' + meson.project_version(),
'-Drelease=' + config_host['PKGVERSION']]
if get_option('werror')
SPHINX_ARGS += [ '-W' ]
endif
if build_docs
configure_file(output: 'index.html',
input: files('index.html.in'),
@@ -15,6 +7,8 @@ if build_docs
man_pages = {
'interop' : {
'qemu-ga.8': (have_tools ? 'man8' : ''),
'qemu-ga-ref.7': 'man7',
'qemu-qmp-ref.7': 'man7',
},
'tools': {
'qemu-img.1': (have_tools ? 'man1' : ''),
@@ -42,6 +36,7 @@ if build_docs
output: [manual + '.stamp'],
input: [files('conf.py'), files(manual / 'conf.py')],
depfile: manual + '.d',
depend_files: sphinx_extn_depends,
command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
'-Ddepfile_stamp=@OUTPUT0@',
'-b', 'html', '-d', private_dir,
@@ -69,5 +64,6 @@ if build_docs
endif
endforeach
alias_target('sphinxdocs', sphinxdocs)
alias_target('html', sphinxdocs)
alias_target('man', sphinxmans)
endif
File diff suppressed because it is too large Load Diff
+1 -1
View File
@@ -27,7 +27,7 @@
#include "qapi/error.h"
#include "qapi/opts-visitor.h"
#include "qapi/qapi-events-run-state.h"
#include "qapi/qapi-visit-misc.h"
#include "qapi/qapi-visit-acpi.h"
#include "qemu/error-report.h"
#include "qemu/module.h"
#include "qemu/option.h"
+1 -1
View File
@@ -3,7 +3,7 @@
#include "migration/vmstate.h"
#include "hw/acpi/cpu.h"
#include "qapi/error.h"
#include "qapi/qapi-events-misc.h"
#include "qapi/qapi-events-acpi.h"
#include "trace.h"
#include "sysemu/numa.h"
+2 -1
View File
@@ -7,7 +7,8 @@
#include "migration/vmstate.h"
#include "trace.h"
#include "qapi/error.h"
#include "qapi/qapi-events-misc.h"
#include "qapi/qapi-events-acpi.h"
#include "qapi/qapi-events-machine.h"
#define MEMORY_SLOTS_NUMBER "MDNR"
#define MEMORY_HOTPLUG_IO_REGION "HPMR"
+1 -1
View File
@@ -12,7 +12,7 @@
#include "qemu/osdep.h"
#include "qapi/error.h"
#include "qapi/qapi-commands-misc.h"
#include "qapi/qapi-commands-machine.h"
#include "qemu/module.h"
#include "hw/acpi/acpi.h"
#include "hw/acpi/aml-build.h"

Some files were not shown because too many files have changed in this diff Show More