| Message ID | 20240619003012.1753577-1-jsnow@redhat.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | qapi: convert "Note" and "Example" sections to rST | expand |
You asked for a summary of my review findings. Here it is:
* PATCH 01: DO-NOT-MERGE, not reviewed
* PATCH 02, 05..07, 10..12: R-by or A-by
* PATCH 03: R-by with straightforward minor adjustments
* PATCH 04, 08: R-by with commit message and doc tweaks
* PATCH 09:
- Commit message tweaks
- You convert "Note:" even in free-form doc, where it isn't
recognized; separate patch or mention in commit message
- You silently move one note; don't, separate patch, or mention in
commit message
- Tweak doc-interleaved-section.json
- A few more notes need to start with a capital letter and / or end
with a period
- I don't like the indentation change
* PATCH 12: Want a positive test
* PATCH 13:
- One hunk should be squashed into PATCH 09
- Accidentally duplicated example should be dropped
- You convert "Example:" even in free-form doc, where it isn't
recognized; separate patch or mention in commit message
- Sphinx doesn't recognize a .. code-block: directive in doc-good.json
- doc-good.txt loses "Example"
- Generated HTML looks somehwat ugly
Feel free to leave reverting indentation changes to me. Same for
starting notes with a capital letter and ending them with a period.
I'm willing to accept ugly HTML along with a promise of future
improvement :)
On Tue, Jun 18, 2024 at 08:29:59PM -0400, John Snow wrote: > 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 virtio things: Reviewed-by: Michael S. Tsirkin <mst@redhat.com> > 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 >