Merge tag 'pull-qapi-2024-08-27' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-08-27

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2024-08-27' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-08-27

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmbNnv8SHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTnfsP+gNO5z7mSHypAD/oGIfYD+HnBrpMK1bL
# WIOH9hLiHEZmMH978WBuKH0Ry8mhEoSNi0jQBB67IzGD4qItSYOSUEfsNBL/VpOG
# lfR8hIt/akdXshrAXB7zJ0D0phnXh93asUIjNpSQkItYxHkO+OphDBPU+anQy2oi
# 71F8z1GSb8DP6rGgcSA7UXq0WUUERdLMrDz8++UAO2hQq9tvQvfNdRh3kTHWZMIP
# urha0Qo6HEGsucQboLaBdJVDdJpkr+offr13CpOrNMFLxZWsnXnsJb3ym+svL4JV
# 8jLp+QAcfomwvaWpNMlFBlgXoHMDkl8T0qhhp598aGdloc6iv9lHipeQOmi541QD
# O/j6sEU4uQ6W3LjPodg/nfHhAyxJ/fI9dKbCVLcSLWHCXbc/yvV623EEWasJIFNE
# lRykAWcZlUvX7UwKfkmqPUutZu1IFhPhSYKOdvw8NZ/llqUOgHcPA50q6wGdkMWC
# wPlhkijo7VGOJf1XJqA9xWuUYikCoBg5mLituzyaCBYlkOv2QBLnj0Yogi2dv79L
# x/tn5/2vDW6tlerCfvF/q5piwXzkDp7KS3i1YRuxnWvbD+b8VAjb7y/7QETpVWXU
# 7fWDIWm5Op7c5KBcj5i/NbI8/guVnvBWsVWXtrJZU9E8vqivC7v93riFOUx3y/Qr
# oBnbTwGgdilh
# =GPSn
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 27 Aug 2024 07:40:15 PM AEST
# 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]

* tag 'pull-qapi-2024-08-27' of https://repo.or.cz/qemu/armbru:
docs/sphinx: fix extra stuff in TOC after freeform QMP sections

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

show more ...

docs/sphinx: fix extra stuff in TOC after freeform QMP sections

Freeform sections with titles are currently generating a TOC entry for
the first paragraph in the section after the header, which is n

docs/sphinx: fix extra stuff in TOC after freeform QMP sections

Freeform sections with titles are currently generating a TOC entry for
the first paragraph in the section after the header, which is not what
we want.

(Easiest to observe directly in the QMP reference manual's
"Introduction" section.)

When freeform sections are parsed, we create both a section header *and*
an empty, title-less section. This causes some problems with sphinx's
post-parse tree transforms, see also 2664f317 - this is a similar issue:
Sphinx doesn't like section-less titles and it also doesn't like
title-less sections.

Modify qapidoc.py to parse text directly into the preceding section
title as child nodes, eliminating the section duplication. This removes
the extra text from the TOC.

Only very, very lightly tested: "it looks right at a glance" :tm:. I am
still in the process of rewriting qapidoc, so I didn't give it much
deeper thought.

Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240822204803.1649762-1-jsnow@redhat.com>

show more ...

Merge tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-17

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-17

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaXoUESHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTatYP/jPlsmx8S6X397COQf6Wd4oEFQEMo/FS
# tWFiHWenPUZ56U3O3lDNIw+5URbhF4aUpxhLGg6cmkrOwK0zPjARI2UNnUnZvPtN
# EHf//KJOpYLsSdkIlIW2nYzB27ps0DRf5PgOGdOOdW32Nuq93FLx7ChDgbpmrijc
# HzByyJIn1QEv/G0aOMLCuTPA7LpGjCAd2a/LjWYpSXB3WGizrS2Rrat7oJYUl8Rz
# mAPgdiE0aH2yWHOTcWabKfN4AsIHCnv7qNOZkumoWpZ0XULbgyK1OO05ju3jRSrB
# 0WiwiE8pEhHz7qstKGcjS1c7pPuId64ubm3RAZ1RUqVvA5TZGucwuYiuQHUVX6jH
# BGzpfojISFzIfTiKemyfqBb1gjXjxT6OIlCtmlJSUCJohb70f0fhX3vniyhzyl1d
# fFTM0jMbmBX89e/o3j6ZXa7anafYNDh5TjTK4BYeAXRqe+jZpvDJUrwu1OZIq1cd
# Wr1RR8qaawpfjD5r9SXu1mX5MPCX4SmNVNoQ7N4ruWjpVojQNmuCRW9yLPIv3yTH
# c5ESND4zdvceW5EF9f5GSIFwnIdGqnUwJyBMcULGoCxz1HougQmGR4bhqSkEl6RD
# GRK+bj3pLdj9f/en62mE6+f5rkEJye3Y5fJ5dn9+Ld09PeUtY59YKnJGg896g55V
# /pGOUWf3L4iY
# =E0F5
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 17 Jul 2024 08:47:29 PM AEST
# 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]

* tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru:
qapi: remove "Example" doc section
qapi: convert "Example" sections with longer prose
qapi: convert "Example" sections with titles
qapi: convert "Example" sections without titles
docs/sphinx: add CSS styling for qmp-example directive
docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
docs/qapidoc: create qmp-example directive
docs/qapidoc: factor out do_parse()
qapi/ui: Drop note on naming of SpiceQueryMouseMode
qapi/sockets: Move deprecation note out of SocketAddress doc comment
qapi/machine: Clarify query-uuid value when none has been specified
qapi/machine: Clean up documentation around CpuInstanceProperties
qapi/pci: Clean up documentation around PciDeviceClass
qapi/qom: Document feature unstable of @x-vfio-user-server

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

show more ...

docs/qapidoc: add QMP highlighting to annotated qmp-example blocks

For any code literal blocks inside of a qmp-example directive, apply and
enforce the QMP lexer/highlighter to those blocks.

This w

docs/qapidoc: add QMP highlighting to annotated qmp-example blocks

For any code literal blocks inside of a qmp-example directive, apply and
enforce the QMP lexer/highlighter to those blocks.

This way, you won't need to write:

```
.. qmp-example::
:annotated:

Blah blah

.. code-block:: QMP

-> { "lorem": "ipsum" }
```

But instead, simply:

```
.. qmp-example::
:annotated:

Blah blah::

-> { "lorem": "ipsum" }
```

Once the directive block is exited, whatever the previous default
highlight language was will be restored; localizing the forced QMP
lexing to exclusively this directive.

Note, if the default language is *already* QMP, this directive will not
generate and restore redundant highlight configuration nodes. We may
well decide that the default language ought to be QMP for any QAPI
reference pages, but this way the directive behaves consistently no
matter where it is used.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240717021312.606116-5-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

docs/qapidoc: create qmp-example directive

This is a directive that creates a syntactic sugar for creating
"Example" boxes very similar to the ones already used in the bitmaps.rst
document, please s

docs/qapidoc: create qmp-example directive

This is a directive that creates a syntactic sugar for creating
"Example" boxes very similar to the ones already used in the bitmaps.rst
document, please see e.g.
https://www.qemu.org/docs/master/interop/bitmaps.html#creation-block-dirty-bitmap-add

In its simplest form, when a custom title is not needed or wanted, and
the example body is *solely* a QMP example:

```
.. qmp-example::

{body}
```

is syntactic sugar for:

```
.. admonition:: Example:

.. code-block:: QMP

{body}
```

When a custom, plaintext title that describes the example is desired,
this form:

```
.. qmp-example::
:title: Defrobnification

{body}
```

Is syntactic sugar for:

```
.. admonition:: Example: Defrobnification

.. code-block:: QMP

{body}
```

Lastly, when Examples are multi-step processes that require non-QMP
exposition, have lengthy titles, or otherwise involve prose with rST
markup (lists, cross-references, etc), the most complex form:

```
.. qmp-example::
:annotated:

This example shows how to use `foo-command`::

{body}

For more information, please see `frobnozz`.
```

Is desugared to:

```
.. admonition:: Example:

This example shows how to use `foo-command`::

{body}

For more information, please see `frobnozz`.
```

Note that :annotated: and :title: options can be combined together, if
desired.

The primary benefit here being documentation source consistently using
the same directive for all forms of examples to ensure consistent visual
styling, and ensuring all relevant prose is visually grouped alongside
the code literal block.

Note that as of this commit, the code-block rST syntax "::" does not
apply QMP highlighting; you would need to use ".. code-block:: QMP". The
very next commit changes this behavior to assume all "::" code blocks
within this directive are QMP blocks.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240717021312.606116-4-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

docs/qapidoc: factor out do_parse()

Factor out the compatibility parser helper into a base class, so it can
be shared by other directives.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: M

docs/qapidoc: factor out do_parse()

Factor out the compatibility parser helper into a base class, so it can
be shared by other directives.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240717021312.606116-3-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

Merge tag 'python-pull-request' of https://gitlab.com/jsnow/qemu into staging

Python: 3.13 compat & sphinx minver bump

# -----BEGIN PGP SIGNATURE-----
#
# iQIzBAABCAAdFiEE+ber27ys35W+dsvQfe+BBqr8OQ

Merge tag 'python-pull-request' of https://gitlab.com/jsnow/qemu into staging

Python: 3.13 compat & sphinx minver bump

# -----BEGIN PGP SIGNATURE-----
#
# iQIzBAABCAAdFiEE+ber27ys35W+dsvQfe+BBqr8OQ4FAmaVXSsACgkQfe+BBqr8
# OQ6tQw//blMWAbcaijg+GyesMrJGJ2xJx0G68DNfhGgpsTcRu9qnd3Q+s56c2pLq
# iJwxaRtTOaYvUhDdcsjpxKJXUIn2WnoqePb31lxXtB9DMxJW6egOvoEzYVpBqlER
# mFp4Feo8bi4/immHcnB8J05fJqGB5Rthp3Bl0s+QH6s2OKHl4rIKYNZTrxwrqKoF
# 8vLg25MMHVzsojXPMfr6VTfxQ84OWXPvHTKMg5E0/OEK6FxGo3PSVTSpc6MtQJuV
# UPAWVqykfuiXC08xg9QpzEvcJGXhGjNDILWWxI+d/8e1rkTiDqOb0LvLhWsa7paO
# LOwsC863YpEPxH0utwfqNQKdTZx1VcnAss4uxULXBucnZ2J7OZp/xZ3xbJCHIbuN
# XRX7/bGKQl3KJ+d+fw5Nto0ANScU+uGaOMAb4tAT+0ChD3uVmkjS4h8D3BAoCBeO
# 9PNtUkpaNGeRAg+iFrGKLTtEUUVsJNIKTlFLSEHRJUCI+/AvX+UvZeEVnlO+qf1/
# rz1chIbw6YgY60NEc7dy7aDhqa9hPTRSYwT79WoPUh74hIiwE3d4TJfL22n5H2jM
# 0ryVPd+lIC7XqF+1FDx/PMxD0mhX2k++WjEpYldsZ2s3UQP5L8M8APKm6MHdMGhn
# rl0fPyVSveF7CMTvy1Y9BTycZHQAOH/9QMM1fm+6JBFgz52QsYg=
# =PLig
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 16 Jul 2024 03:32:27 AM AEST
# gpg: using RSA key F9B7ABDBBCACDF95BE76CBD07DEF8106AAFC390E
# gpg: Good signature from "John Snow (John Huston) <jsnow@redhat.com>" [unknown]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: FAEB 9711 A12C F475 812F 18F2 88A9 064D 1835 61EB
# Subkey fingerprint: F9B7 ABDB BCAC DF95 BE76 CBD0 7DEF 8106 AAFC 390E

* tag 'python-pull-request' of https://gitlab.com/jsnow/qemu:
docs: remove Sphinx 1.x compatibility code
Python: bump minimum sphinx version to 3.4.3
python: enable testing for 3.13
iotests: Change imports for Python 3.13
python: Do not use pylint 3.2.4 with python 3.8
python: linter changes for pylint 3.x

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

show more ...

docs: remove Sphinx 1.x compatibility code

In general, the Use_SSI workaround is no longer needed, and neither is
the pre-1.6 logging shim for kerneldoc.

Signed-off-by: John Snow <jsnow@redhat.com>

docs: remove Sphinx 1.x compatibility code

In general, the Use_SSI workaround is no longer needed, and neither is
the pre-1.6 logging shim for kerneldoc.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-id: 20240703175235.239004-3-jsnow@redhat.com
[rebased on top of origin/master. --js]
Signed-off-by: John Snow <jsnow@redhat.com>

show more ...

Merge tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaI6xcSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTTbQP/AonsqGYQyOPCWae9dfDt+Wy+k2gthoB
# dn/3SRjYnA23avEv2/AGAPxgp5MHkpdhh8eqNjWq9QgqgEUh/m0nJztS/MiLMHsR
# /PENPy4V2QFf7s5XtIutLiKXgGbzwtHxrbwnCNyQZW6dAK67VBTq5hPQSxFwBVga
# FDVm+DS2JehJ7IPMVmPT5gjI2cyDYNc/rxbvcbcb5SqirfJdPFk9nMJUrQ0Qubfs
# c9D6l8Cwzbm4JfSeRThs8v9CsDZ1+OIXnpDgGAP9hr7+yYFsovLSHfiLGFxnFXiN
# gSKLBNRIzXnC9cFsKY4jXuqFoSFblRccqCtPSYb7sAp3OVwKq3kA/XNuPIAPii8S
# cm+bhVJ3lyXUW5/6qruS5tOEkpsTnXC45Uw9nvZDEVXANMn3viZ1qInxKak8Nr+p
# k0bOHGE4NzRKkAvGDaTooUOlhG4iy9M+Q4dTcwKIoXTs1Euo8uOjAL+jGwT2pan5
# fb/P1cIqMgMpwSQjwIs7LoYMk20FF44CPtuwA+m85iLbTiiuUfQ4bTnVNMOQMibq
# 3QWIrEDfxwrvwMPsv/u/hcc5d2Tb+5QP9CeVmT9woSXJqU2g4yvKKP9JBf7jUFMC
# fTpNRcHOWsIoz+AgOrUeYe67fLpqUWQii08JhPg5f4ybbEzkzZub0zOKNFLYumG0
# VT3BQlO+8LdW
# =RwDq
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 05 Jul 2024 11:58:31 PM PDT
# 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]

* tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru:
sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
qapi/parser: don't parse rST markup as section headers
qapi: add markup to note blocks
qapi: update prose in note blocks
qapi: convert "Note" sections to plain rST
qapi: nail down convention that Errors sections are lists
qapi: fix non-compliant JSON examples
docs/qapidoc: fix nested parsing under untagged sections
qapi/parser: fix comment parsing immediately following a doc block
qapi/parser: preserve indentation in QAPIDoc sections
docs/qapidoc: delint a tiny portion of the module
docs/qapidoc: remove unused intersperse function
qapi: linter fixups

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

show more ...

sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments

When a command's arguments are specified as an explicit type T,
generated documentation points to the members of T.

Example:

sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments

When a command's arguments are specified as an explicit type T,
generated documentation points to the members of T.

Example:

##
# @announce-self:
#
# Trigger generation of broadcast RARP frames to update network
[...]
##
{ 'command': 'announce-self', 'boxed': true,
'data' : 'AnnounceParameters'}

generates

"announce-self" (Command)
-------------------------

Trigger generation of broadcast RARP frames to update network
[...]

Arguments
~~~~~~~~~

The members of "AnnounceParameters"

Except when the command takes its arguments unboxed , i.e. it doesn't
have 'boxed': true, we generate *nothing*. A few commands have a
reference in their doc comment to compensate, but most don't.

Example:

##
# @blockdev-snapshot-sync:
#
# Takes a synchronous snapshot of a block device.
#
# For the arguments, see the documentation of BlockdevSnapshotSync.
[...]
##
{ 'command': 'blockdev-snapshot-sync',
'data': 'BlockdevSnapshotSync',
'allow-preconfig': true }

generates

"blockdev-snapshot-sync" (Command)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Takes a synchronous snapshot of a block device.

For the arguments, see the documentation of BlockdevSnapshotSync.
[...]

Same for event data.

Fix qapidoc.py to generate the reference regardless of boxing. Delete
now redundant references in the doc comments.

Fixes: 4078ee5469e5 (docs/sphinx: Add new qapi-doc Sphinx extension)
Cc: qemu-stable@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240628112756.794237-1-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>

show more ...

docs/qapidoc: fix nested parsing under untagged sections

Sphinx does not like sections without titles, because it wants to
convert every section into a reference. When there is no title, it
struggle

docs/qapidoc: fix nested parsing under untagged sections

Sphinx does not like sections without titles, because it wants to
convert every section into a reference. When there is no title, it
struggles to do this and transforms the tree inproperly.

Depending on the rST used, this may result in an assertion error deep in
the docutils HTMLWriter.

(Observed when using ".. admonition:: Notes" under such a section - When
this is transformed with its own <title> element, Sphinx is fooled into
believing this title belongs to the section and incorrect mutates the
docutils tree, leading to errors during rendering time.)

When parsing an untagged section (free paragraphs), skip making a hollow
section and instead append the parse results to the prior section.

Many Bothans died to bring us this information.

The resulting output changes are basically invisible.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-8-jsnow@redhat.com>
[Mention output changes in commit message]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi/parser: preserve indentation in QAPIDoc sections

Change get_doc_indented() to preserve indentation on all subsequent text
lines, and create a compatibility dedent() function for qapidoc.py that

qapi/parser: preserve indentation in QAPIDoc sections

Change get_doc_indented() to preserve indentation on all subsequent text
lines, and create a compatibility dedent() function for qapidoc.py that
removes indentation the same way get_doc_indented() did.

This is being done for the benefit of a new qapidoc generator which
requires that indentation in argument and features sections are
preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
dolor sit amet
consectetur adipiscing elit
```

would have its body text be parsed into:

```
lorem ipsum
dolor sit amet
consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so that
the entire block can be parsed directly as rST. This patch would now
parse that segment into:

```
lorem ipsum
dolor sit amet
consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists in
rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
dolor sit amet
consectetur apidiscing elit
```

...and can be formed by the simple concatenation of the field list
construct and the body text. The indents help preserve the continuation
of a block-level element, and further allow the use of additional rST
block-level constructs such as code blocks, lists, and other such
markup.

This understandably breaks the existing qapidoc.py; so a new function is
added there to dedent the text for compatibility. Once the new generator
is merged, this function will not be needed any longer and can be
dropped.

I verified this patch changes absolutely nothing by comparing the
md5sums of the QMP ref html pages both before and after the change, so
it's certified inert. QAPI test output has been updated to reflect the
new strategy of preserving indents for rST.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-6-jsnow@redhat.com>
[Lost commit message paragraph restored]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

docs/qapidoc: delint a tiny portion of the module

In a forthcoming series that adds a new QMP documentation generator, it
will be helpful to have a linting baseline. However, there's no need to
shuf

docs/qapidoc: delint a tiny portion of the module

In a forthcoming series that adds a new QMP documentation generator, it
will be helpful to have a linting baseline. However, there's no need to
shuffle around the deck chairs too much, because most of this code will
be removed once that new qapidoc generator (the "transmogrifier") is in
place.

To ease my pain: just turn off the black auto-formatter for most, but
not all, of qapidoc.py. This will help ensure that *new* code follows a
coding standard without bothering too much with cleaning up the existing
code.

Code that I intend to keep is still subject to the delinting beam.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-5-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

docs/qapidoc: remove unused intersperse function

This function has been unused since since commit
fd62bff901b (sphinx/qapidoc: Drop code to generate doc for simple
union tag).

Signed-off-by: John S

docs/qapidoc: remove unused intersperse function

This function has been unused since since commit
fd62bff901b (sphinx/qapidoc: Drop code to generate doc for simple
union tag).

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240626222128.406106-4-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

Merge tag 'pull-qapi-2024-05-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-05-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2024-05-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-05-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmY4uIASHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTCYoQAK8Y2SSPlRqwdyYWqQHcPuQe4ThvnT2l
# y1Dzcy0MGKdeDQng+lyMh9x50U6vMd33TaWEDZ4PEprSLirWnRIIL9/qgrc+obYB
# LfncQR7BRLEPYRA0cQwvSBNzSLgCiySoa9x98yCB1ZZGQsAMz4p1j8qDpJFAL2qa
# VThXFcBaUOPRKFDwp03r8n8PFsaqaBVjI/2YX13EyJksaPNLNT6Z2xfcgREXFu2I
# gWfFR21kJwkUAgkfc6LhmqlpKXBpKQ+bWCmV1G/+LZosid3B8jfKOfOx4s9q9g5G
# N7HVRSHlqPyGQeJGaiiKgPZyoRh65L0YRa3OtYoJL9ngx1P7opAGxnxSsARduNg3
# yQbbFY4c99HuxgxfMLwRPWr6Xm3c5DEvdIwoVRWm1ajJynbLWNiTN/uQs+tIEFbr
# 4usxqAQRo2G5WkY9JGuDuBJkZTp1/6pEM0xVrRgGYH9jr8LZrS2HPrnbcsa3eqAl
# UqSfu8HAL8j1wiBAr83DQe+SuoyRfrnFaTNYAILFG4RUsWF2u44RvkceGroyq3s1
# mgHFZGF0+m8K7TXqeJvkSgg4wr2AnavXrb79Zz2JVut0X6K6S4AbueTBIn8zT2EX
# uGHhm4ZW5JUq6Wz6bQtq6/IUa/k2pAlszVFHe3Yn50J3CUU5dR/nYry7Cx4Q6/KT
# h4vzopMBjVv1
# =3Pxa
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 06 May 2024 04:01:20 AM PDT
# 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]

* tag 'pull-qapi-2024-05-06' of https://repo.or.cz/qemu/armbru:
qapi: Simplify QAPISchemaVariants @tag_member
qapi: Move conditional code from QAPISchemaVariants to its subtypes
qapi: Rename QAPISchemaAlternateType.variants to .alternatives
qapi: Rename QAPISchemaObjectType.variants to .branches
qapi: Rename visitor parameter @variants to @alternatives
qapi: Rename visitor parameter @variants to @branches
qapi: New QAPISchemaBranches, QAPISchemaAlternatives

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

show more ...

qapi: Rename visitor parameter @variants to @alternatives

A previous commit narrowed the type of .visit_alternate_type()
parameter @variants from QAPISchemaVariants to QAPISchemaAlternatives.
Rename

qapi: Rename visitor parameter @variants to @alternatives

A previous commit narrowed the type of .visit_alternate_type()
parameter @variants from QAPISchemaVariants to QAPISchemaAlternatives.
Rename it to @alternatives.

One of them passes @alternatives to helper function
gen_visit_alternate(). Rename its @variants parameter to
@alternatives as well.

Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

qapi: Rename visitor parameter @variants to @branches

The previous commit narrowed the type of .visit_object_type()
parameter @variants from QAPISchemaVariants to QAPISchemaBranches.
Rename it to @b

qapi: Rename visitor parameter @variants to @branches

The previous commit narrowed the type of .visit_object_type()
parameter @variants from QAPISchemaVariants to QAPISchemaBranches.
Rename it to @branches.

Same for .visit_object_type_flat().

A few of these pass @branches to helper functions:
QAPISchemaGenRSTVisitor.visit_object_type() to ._nodes_for_members()
and ._nodes_for_variant_when(), and
QAPISchemaGenVisitVisitor.visit_object_type() to
gen_visit_object_members(). Rename the helpers' @variants parameters
to @branches as well.

Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

Merge tag 'pull-qapi-2024-02-26' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-02-26

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2024-02-26' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-02-26

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmXcXWUSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTMqQP/3aZ8Jm48Bh4sG5JxJ01aM3iX//cuA8X
# 0xoKBfDWkwKvUDE+sv+2qH1WxcNGS4wb/lLaT6Jf0S8EzzelDx5zYGwXXsmBljoZ
# Kh8BI7Oe1SQwI5Z36q/efG9isQ6nqGyxR9xu1BTbJCSOZXzxpOBljbSyXOtKc5C/
# HM4TK82geLLgm04gMkoPmFdu3BXDfPYnGJ3UNLE9hTPoW7XL4EGFAOOWuDcrSF5n
# OdHjfK9TK9PcxsJGqVUqLHwfRQYLMBni6OkurdFOVdLM1v4C707NuryjaGQc1WEI
# xKwsJDKR+zG7vGu4y594HN/Ivoaqci8MMTbDgVmHZ3LaI3RUfSplGTDSYLjCp8jz
# XDx82+hhmb/2ZMmE0tarUQyv0dimrZSEh6cWWHMvp63edKTywoB/eIDR9lBteTZe
# wRvkSKmN6oKJI8cNiiXZqw5y2JPvhNag4Xdr8kHKwHgxVWP+SneInLCC+T2SMgio
# EeC+S4CVTdjPvEC96dOGrsqKn+gl/h74PK5ZdTaD1B6XCuIalsRn6REujqW6Ew6n
# rj7Iec/noejeOsflzBWRKT91t2Zck/MRLhX9nYqybBxyxUFvFS7M6ok/iq4oEtZR
# lJooF6iiq8xtEzoLselfGFAZTUxhwLdUfXPVDx7p5HDpJci88xv6zmav9eE84JbH
# mBD55GEH17ka
# =81Zq
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 26 Feb 2024 09:44:05 GMT
# 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

* tag 'pull-qapi-2024-02-26' of https://repo.or.cz/qemu/armbru:
qapi: Divorce QAPIDoc from QAPIParseError
qapi: Reject multiple and empty feature descriptions
qapi: Rewrite doc comment parser
qapi: Merge adjacent untagged sections
qapi: Call QAPIDoc.check() always
qapi: Recognize section tags and 'Features:' only after blank line
qapi: Require descriptions and tagged sections to be indented
qapi: Reject section heading in the middle of a doc comment
qapi: Rename QAPIDoc.Section.name to .tag
qapi: Improve error message for empty doc sections
qapi: Improve error position for bogus invalid "Returns" section
qapi: Improve error position for bogus argument descriptions
sphinx/qapidoc: Drop code to generate doc for simple union branch
tests/qapi-schema: Cover 'Features:' not followed by descriptions
tests/qapi-schema: Cover duplicate 'Features:' line
tests/qapi-schema: Fix test 'QAPI rST doc'
qapi: Misc cleanups to migrate QAPIs

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

qapi: Rename QAPIDoc.Section.name to .tag

Since the previous commit, QAPIDoc.Section.name is either
None (untagged section) or the section's tag string ('Returns',
'@name', ...). Rename it to .tag.

qapi: Rename QAPIDoc.Section.name to .tag

Since the previous commit, QAPIDoc.Section.name is either
None (untagged section) or the section's tag string ('Returns',
'@name', ...). Rename it to .tag.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-9-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: Improve error message for empty doc sections

Improve the message for an empty tagged section from

empty doc section 'Note'

to

text required after 'Note:'

and the message for an emp

qapi: Improve error message for empty doc sections

Improve the message for an empty tagged section from

empty doc section 'Note'

to

text required after 'Note:'

and the message for an empty argument or feature description from

empty doc section 'foo'

to

text required after '@foo:'

Improve the error position to refer to the beginning of the empty
section instead of its end.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-8-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

sphinx/qapidoc: Drop code to generate doc for simple union branch

Commit 4e99f4b12c0 (qapi: Drop simple unions) eliminated implicitly
defined union branch types, except for the empty object type
'q_

sphinx/qapidoc: Drop code to generate doc for simple union branch

Commit 4e99f4b12c0 (qapi: Drop simple unions) eliminated implicitly
defined union branch types, except for the empty object type
'q_empty'. QAPISchemaGenRSTVisitor._nodes_for_members() still has
code to generate documentation for implicitly defined union branch
types. It does nothing for 'q_empty'. Simplify.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-5-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

Merge tag 'pull-qapi-2024-02-12' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-02-12

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2024-02-12' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-02-12

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmXJ4PsSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTDwsP/iEdmZmjoxMedTzec+GGl5QxfMkqLn14
# eX2jXtzLGZMjGMh4lvMaAdn0AJ3VnBOqxly14sMK6TMWGZkNKJpKF+2Cj8IKte1o
# MlpS1N/7rZxew+B9HkulhS+6UFB3Jndsflm2ot4g+rRjohJCw0v0GapEqjQg6CKp
# efJhiPuBSImm2MSx+n4dj8gkcFOMrgo6oc2ZpN0ypvGb4mupPpnNj6v12yZL8FUM
# Enwsk+pBLQWoYxI9MFDGc0gW9ZBlEdP/nVq/PbglD06Urc241AHGYqT7XLT0oHLl
# 6NA4v3N4GPdSe6oJdOHDFVR+/uPKiiyrseTdYTSGgAN8gcRtHam4WWhqSDIN3Afl
# y41A9ZKkW51TpdszQ6wCdrgbTH5z6K5vnwWfVTwIgdI0mrDcAGWnc2Yr7m6c3fS8
# /Vz00J7OC0P1nXh0IeRxXExXSmaGUUgS3T/KBXPYr0PQPe7Qd+1eTQN6LaliEMRH
# dRpXQabjLmztMhc5VXCv8ihwa7mNVaEn++uRrdKoWOvIQEp0ZeZfxCzp+/2mGPJ0
# YKJc7Ja260h2Y00/Zu2XiwjdzgG+h+QuJO/3OFsZIV5ftFqSBRMCHiGEfANHidld
# Cpo0efeWWTPdV8BQOirGGr0qtDTmgFMFCZTJMsI/g0m9sMCv0WbTtmWNThwaI3uD
# MKnEGG+KX7vD
# =nhrQ
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 12 Feb 2024 09:12:27 GMT
# 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

* tag 'pull-qapi-2024-02-12' of https://repo.or.cz/qemu/armbru:
MAINTAINERS: Cover qapi/stats.json
MAINTAINERS: Cover qapi/cxl.json
qapi/migration: Add missing tls-authz documentation
qapi: Add missing union tag documentation
qapi: Move @String out of common.json to discourage reuse
qapi: Improve documentation of file descriptor socket addresses
qapi: Plug trivial documentation holes around former simple unions
qapi/dump: Clean up documentation of DumpGuestMemoryCapability
qapi/yank: Clean up documentaion of yank
qga/qapi-schema: Plug trivial documentation holes
qga/qapi-schema: Clean up documentation of guest-set-vcpus
qga/qapi-schema: Clean up documentation of guest-set-memory-blocks
qapi: Require member documentation (with loophole)
sphinx/qapidoc: Drop code to generate doc for simple union tag
qapi: Indent tagged doc comment sections properly
qapi/block-core: Fix BlockLatencyHistogramInfo doc markup
docs/devel/qapi-code-gen: Tweak doc comment whitespace
docs/devel/qapi-code-gen: Normalize version refs x.y.0 to just x.y

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

sphinx/qapidoc: Drop code to generate doc for simple union tag

QAPISchemaGenRSTVisitor._nodes_for_members() has a special case to
auto-generate documentation for a union tag member of implicit (enum

sphinx/qapidoc: Drop code to generate doc for simple union tag

QAPISchemaGenRSTVisitor._nodes_for_members() has a special case to
auto-generate documentation for a union tag member of implicit (enum)
type that lacks documentation.

This was useful for simple unions, where the tag member's type was
implicitly. The only implicit enum type left today is 'QType'. Not
worth a special case. Drop. No change to generated documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-6-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

Merge tag 'pull-qapi-2023-11-13' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2023-11-13

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFA

Merge tag 'pull-qapi-2023-11-13' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2023-11-13

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmVR7j4SHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTmT0P/imN9c6xnkx8Kff0iEaT88N8YUHEu5gt
# ECiQtfpbU8y8itIrWpuXWk7HUC1Jp397vKgUhmmr5Im32vx1waUGz/zxdBiitw0a
# 2McXfD6Lbz3LN+q002Vq0QjP3tMeoc8DoP/CagmdXniGrxyJSs/oIsUAdqZnymug
# ZREYRUlbrgJ8XA06n9qIaCGpiihBLl2XBbx4SV9JWle/9vKpII9EBrWNXTcCkde3
# W6gHEKgGAKa1NGYMJtOncanpnzVP0qoLmb3jmiR9tpj3YBB/5LP9l4O11DTC+PQ5
# nn+OmtmjuKE2a2C79Y8VCbRPR6MPSDDbuWwu7Q+A7vXi/1gnkMeXH+A6jE0d3y+p
# PWKqBK65U+yS0IwiUGpMpcGo2WtZiBLzp3ragt+gzi3gV5GvEvPv0uvcEd66in95
# +M2RoVhkbi+e03mF+vDldvbwBYPwlNdgAX/ly7SR76YZybSMK0Jkp7yfvxN35LJc
# kgCo0CY9kAYYUgPUJMiPhaxSfRVk738Qex7QCvFwDiZE8l4XEwoT1PRO0fs8G5aI
# /Yz7hhjkaLw+i+k/tCVCVe+hOgMxxVUz/gZzV4+yrfQNxz41v4WqCfE8a+m6RROo
# TaceVJPKqsyoJ2zmS+CpEPFWkWXEQSQ14yu2wdF8wMyKEWDS4yhRG78rnYC2/ZhC
# zullCL7QfFbf
# =bGOD
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 13 Nov 2023 04:37:02 EST
# 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

* tag 'pull-qapi-2023-11-13' of https://repo.or.cz/qemu/armbru:
tests/qapi-schema: Tidy up pylint warnings and advice
sphinx/qapidoc: Tidy up pylint warning raise-missing-from
qapi: Fix QAPISchemaEntity.__repr__()

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>

show more ...

sphinx/qapidoc: Tidy up pylint warning raise-missing-from

Pylint advises:

docs/sphinx/qapidoc.py:518:12: W0707: Consider explicitly re-raising using 'raise ExtensionError(str(err)) from err' (r

sphinx/qapidoc: Tidy up pylint warning raise-missing-from

Pylint advises:

docs/sphinx/qapidoc.py:518:12: W0707: Consider explicitly re-raising using 'raise ExtensionError(str(err)) from err' (raise-missing-from)

>From its manual:

Python's exception chaining shows the traceback of the current
exception, but also of the original exception. When you raise a
new exception after another exception was caught it's likely that
the second exception is a friendly re-wrapping of the first
exception. In such cases `raise from` provides a better link
between the two tracebacks in the final error.

Makes sense, so do it.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20231025092159.1782638-2-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>

show more ...