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

[John Snow]

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