Howdy - this patch series is the first batch of patches meant to prepare
the QAPI documentation for a new Sphinx module that adds
cross-references, an index, improved inlining, elision of types unseen
on the wire, and other goodies.

This series addresses just existing code and documentation that needs to
be changed and doesn't introduce anything new just yet - except the rST
conversion of Notes and Examples sections, which DOES impact the
existing QAPI documentation generation.

If you're CC'd on this series, it's *probably* because I've adjusted
some QAPI documentation that you're the maintainer of - In most cases,
these changes are purely mechanical (converting QAPI sections into pure
rST) and probably nothing too interesting. In a small handful of cases
(patches 15-17), I've been a bit more invasive and you may want to take
a quick peek.

Overview:

Patches 1-3: linter/typing cleanup
Patches 4-12: QAPI generator fixes/miscellany
Patch 13: qapidoc.py fix (to prepare for rST conversion)
Patches 14-20: QAPI documentation modifications, rST conversion

Sorry,
--js

John Snow (20):
  [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
  qapi: linter fixups
  docs/qapidoc: delint a tiny portion of the module
  qapi/parser: preserve indentation in QAPIDoc sections
  qapi/parser: adjust info location for doc body section
  qapi/parser: fix comment parsing immediately following a doc block
  qapi/parser: add semantic 'kind' parameter to QAPIDoc.Section
  qapi/parser: differentiate intro and outro paragraphs
  qapi/parser: add undocumented stub members to all_sections
  qapi/schema: add __iter__ method to QAPISchemaVariants
  qapi/schema: add doc_visible property to QAPISchemaDefinition
  qapi/source: allow multi-line QAPISourceInfo advancing
  docs/qapidoc: fix nested parsing under untagged sections
  qapi: fix non-compliant JSON examples
  qapi: remove developer factoring comments from QAPI doc blocks
  qapi: rewrite StatsFilter comment
  qapi: rewrite BlockExportOptions doc block
  qapi: ensure all errors sections are uniformly typset
  qapi: convert "Note" sections to plain rST
  qapi: convert "Example" sections to rST

 docs/sphinx/qapidoc.py                        |  62 ++++--
 qapi/acpi.json                                |   6 +-
 qapi/audio.json                               |   5 +-
 qapi/block-core.json                          | 195 ++++++++++--------
 qapi/block-export.json                        |  16 +-
 qapi/block.json                               |  62 +++---
 qapi/char.json                                |  53 +++--
 qapi/control.json                             |  32 +--
 qapi/crypto.json                              |  33 ++-
 qapi/dump.json                                |  14 +-
 qapi/introspect.json                          |   6 +-
 qapi/machine-target.json                      |  29 +--
 qapi/machine.json                             | 138 +++++++------
 qapi/migration.json                           | 159 +++++++++-----
 qapi/misc-target.json                         |  33 ++-
 qapi/misc.json                                | 139 +++++++------
 qapi/net.json                                 |  49 +++--
 qapi/pci.json                                 |  11 +-
 qapi/qapi-schema.json                         |   6 +-
 qapi/qdev.json                                |  45 ++--
 qapi/qom.json                                 |  69 +++----
 qapi/replay.json                              |  12 +-
 qapi/rocker.json                              |  30 +--
 qapi/run-state.json                           |  63 +++---
 qapi/sockets.json                             |  10 +-
 qapi/stats.json                               |  30 ++-
 qapi/tpm.json                                 |   9 +-
 qapi/trace.json                               |   6 +-
 qapi/transaction.json                         |  13 +-
 qapi/ui.json                                  | 107 +++++-----
 qapi/virtio.json                              |  50 ++---
 qapi/yank.json                                |   6 +-
 qga/qapi-schema.json                          |  48 ++---
 scripts/qapi-lint.sh                          |  51 +++++
 scripts/qapi/Makefile                         |   5 +
 scripts/qapi/introspect.py                    |  12 +-
 scripts/qapi/parser.py                        | 104 ++++++++--
 scripts/qapi/schema.py                        |  54 ++++-
 scripts/qapi/source.py                        |   4 +-
 scripts/qapi/types.py                         |   4 +-
 scripts/qapi/visit.py                         |   9 +-
 tests/qapi-schema/doc-empty-section.err       |   2 +-
 tests/qapi-schema/doc-empty-section.json      |   2 +-
 tests/qapi-schema/doc-good.json               |  18 +-
 tests/qapi-schema/doc-good.out                |  61 +++---
 tests/qapi-schema/doc-good.txt                |  31 +--
 .../qapi-schema/doc-interleaved-section.json  |   2 +-
 47 files changed, 1152 insertions(+), 753 deletions(-)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile

-- 
2.44.0

On Tue, May 14, 2024 at 05:57:19PM -0400, John Snow wrote:
> Howdy - this patch series is the first batch of patches meant to prepare
> the QAPI documentation for a new Sphinx module that adds
> cross-references, an index, improved inlining, elision of types unseen
> on the wire, and other goodies.
> 
> This series addresses just existing code and documentation that needs to
> be changed and doesn't introduce anything new just yet - except the rST
> conversion of Notes and Examples sections, which DOES impact the
> existing QAPI documentation generation.
> 
> If you're CC'd on this series, it's *probably* because I've adjusted
> some QAPI documentation that you're the maintainer of - In most cases,
> these changes are purely mechanical (converting QAPI sections into pure
> rST) and probably nothing too interesting. In a small handful of cases
> (patches 15-17), I've been a bit more invasive and you may want to take
> a quick peek.
> 
> Overview:
> 
> Patches 1-3: linter/typing cleanup
> Patches 4-12: QAPI generator fixes/miscellany
> Patch 13: qapidoc.py fix (to prepare for rST conversion)
> Patches 14-20: QAPI documentation modifications, rST conversion
> 
> Sorry,
> --js
> 
> John Snow (20):
>   [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
>   qapi: linter fixups
>   docs/qapidoc: delint a tiny portion of the module
>   qapi/parser: preserve indentation in QAPIDoc sections
>   qapi/parser: adjust info location for doc body section
>   qapi/parser: fix comment parsing immediately following a doc block
>   qapi/parser: add semantic 'kind' parameter to QAPIDoc.Section
>   qapi/parser: differentiate intro and outro paragraphs
>   qapi/parser: add undocumented stub members to all_sections
>   qapi/schema: add __iter__ method to QAPISchemaVariants
>   qapi/schema: add doc_visible property to QAPISchemaDefinition
>   qapi/source: allow multi-line QAPISourceInfo advancing
>   docs/qapidoc: fix nested parsing under untagged sections
>   qapi: fix non-compliant JSON examples
>   qapi: remove developer factoring comments from QAPI doc blocks
>   qapi: rewrite StatsFilter comment
>   qapi: rewrite BlockExportOptions doc block
>   qapi: ensure all errors sections are uniformly typset
>   qapi: convert "Note" sections to plain rST
>   qapi: convert "Example" sections to rST
> 
>  docs/sphinx/qapidoc.py                        |  62 ++++--
>  qapi/acpi.json                                |   6 +-
>  qapi/audio.json                               |   5 +-
>  qapi/block-core.json                          | 195 ++++++++++--------
>  qapi/block-export.json                        |  16 +-
>  qapi/block.json                               |  62 +++---
>  qapi/char.json                                |  53 +++--
>  qapi/control.json                             |  32 +--
>  qapi/crypto.json                              |  33 ++-
>  qapi/dump.json                                |  14 +-
>  qapi/introspect.json                          |   6 +-
>  qapi/machine-target.json                      |  29 +--
>  qapi/machine.json                             | 138 +++++++------
>  qapi/migration.json                           | 159 +++++++++-----
>  qapi/misc-target.json                         |  33 ++-
>  qapi/misc.json                                | 139 +++++++------
>  qapi/net.json                                 |  49 +++--
>  qapi/pci.json                                 |  11 +-
>  qapi/qapi-schema.json                         |   6 +-
>  qapi/qdev.json                                |  45 ++--
>  qapi/qom.json                                 |  69 +++----
>  qapi/replay.json                              |  12 +-
>  qapi/rocker.json                              |  30 +--
>  qapi/run-state.json                           |  63 +++---
>  qapi/sockets.json                             |  10 +-
>  qapi/stats.json                               |  30 ++-
>  qapi/tpm.json                                 |   9 +-
>  qapi/trace.json                               |   6 +-
>  qapi/transaction.json                         |  13 +-
>  qapi/ui.json                                  | 107 +++++-----
>  qapi/virtio.json                              |  50 ++---
>  qapi/yank.json                                |   6 +-
>  qga/qapi-schema.json                          |  48 ++---
>  scripts/qapi-lint.sh                          |  51 +++++
>  scripts/qapi/Makefile                         |   5 +
>  scripts/qapi/introspect.py                    |  12 +-
>  scripts/qapi/parser.py                        | 104 ++++++++--
>  scripts/qapi/schema.py                        |  54 ++++-
>  scripts/qapi/source.py                        |   4 +-
>  scripts/qapi/types.py                         |   4 +-
>  scripts/qapi/visit.py                         |   9 +-
>  tests/qapi-schema/doc-empty-section.err       |   2 +-
>  tests/qapi-schema/doc-empty-section.json      |   2 +-
>  tests/qapi-schema/doc-good.json               |  18 +-
>  tests/qapi-schema/doc-good.out                |  61 +++---
>  tests/qapi-schema/doc-good.txt                |  31 +--
>  .../qapi-schema/doc-interleaved-section.json  |   2 +-
>  47 files changed, 1152 insertions(+), 753 deletions(-)
>  create mode 100755 scripts/qapi-lint.sh
>  create mode 100644 scripts/qapi/Makefile
> 
> -- 
> 2.44.0
> 
> 

For block-core.json/block-export.json/block.json:

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