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
