This series focuses primarily on converting our existing QAPI/QMP documentation to remove special "Note" and "Example" sections in favor of rST markup for the same.
This is being done primarily to reduce the number of specially parsed QAPI sections we have in favor of allowing fully arbitrary rST markup for greater flexibility and freedom in styling the rendered HTML documentation. (A tangible side benefit is that the new qapidoc generator has fewer sections to reason about when it splices inherited documentation together for the QMP reference manual; docs largely preserve the order of documentation "as written" instead of needing to splice multiple separate sections together. A goal of the new generator is to eventually remove all tagged sections except for "members" and "features".) Known issues: - The caption syntax for QMP examples is a little ugly in rendered HTML output; My CSS intern wasn't available before publication time to fix it ;) -- Will fix with an amendment patch at next opportunity. Any feedback not implemented should be interpreted as evidence of a forgetful (rather than a spiteful) mind. Please remind me where appropriate. --js John Snow (13): [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: fix comment parsing immediately following a doc block docs/qapidoc: fix nested parsing under untagged sections qapi: fix non-compliant JSON examples qapi: ensure all errors sections are uniformly typset qapi: convert "Note" sections to plain rST qapi: update prose in note blocks qapi: add markup to note blocks qapi/parser: don't parse rST markup as section headers qapi: convert "Example" sections to rST docs/devel/qapi-code-gen.rst | 25 +-- docs/sphinx/qapidoc.py | 103 ++++++++---- qapi/acpi.json | 6 +- qapi/block-core.json | 148 +++++++++------- qapi/block.json | 62 ++++--- qapi/char.json | 48 ++++-- qapi/control.json | 32 ++-- qapi/dump.json | 14 +- qapi/introspect.json | 6 +- qapi/machine-target.json | 29 ++-- qapi/machine.json | 125 ++++++++------ qapi/migration.json | 159 ++++++++++++------ qapi/misc-target.json | 33 ++-- qapi/misc.json | 139 ++++++++------- qapi/net.json | 42 +++-- qapi/pci.json | 11 +- qapi/qapi-schema.json | 6 +- qapi/qdev.json | 45 ++--- qapi/qom.json | 39 +++-- qapi/replay.json | 12 +- qapi/rocker.json | 30 ++-- qapi/run-state.json | 63 ++++--- qapi/sockets.json | 10 +- qapi/stats.json | 22 +-- qapi/tpm.json | 9 +- qapi/trace.json | 6 +- qapi/transaction.json | 13 +- qapi/ui.json | 93 +++++----- qapi/vfio.json | 3 +- qapi/virtio.json | 50 +++--- qapi/yank.json | 6 +- qga/qapi-schema.json | 48 +++--- scripts/qapi-lint.sh | 59 +++++++ scripts/qapi/Makefile | 5 + scripts/qapi/introspect.py | 8 +- scripts/qapi/parser.py | 40 ++++- scripts/qapi/schema.py | 6 +- scripts/qapi/visit.py | 5 +- tests/qapi-schema/doc-empty-section.err | 2 +- tests/qapi-schema/doc-empty-section.json | 2 +- tests/qapi-schema/doc-good.json | 21 ++- tests/qapi-schema/doc-good.out | 62 ++++--- tests/qapi-schema/doc-good.txt | 31 ++-- .../qapi-schema/doc-interleaved-section.json | 2 +- 44 files changed, 1036 insertions(+), 644 deletions(-) create mode 100755 scripts/qapi-lint.sh create mode 100644 scripts/qapi/Makefile -- 2.44.0