Re: [PATCH 00/20] qapi: new sphinx qapi domain pre-requisites

[Stefan Hajnoczi]

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>

signature.asc
Description: PGP signature