| Message ID | 20240514215740.940155-1-jsnow@redhat.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | qapi: new sphinx qapi domain pre-requisites | expand |
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>