Based-on: 20250612214200.1208340-1-js...@redhat.com
[PATCH v4 0/4] qapi: add auto-generated return docs
Hi, this patch series is a *mostly* mechanical application of QAPI
cross-references to the QAPI/QMP documentation. I exported all
cross-referenceable symbols from the QMP QAPI schema and ran them
through a script that converted any matching words to a cross-reference.
I then used `git add -p` and only added changes that looked reasonable,
omitting many cases of converting common words like "stop",
"transaction", "eject", "String" etc when it wasn't immediately clear
that it was appropriate. I probably missed a few ... in either
direction.
I'd like to ask maintainers for each subsystem to review the changes and
confirm that they make sense. To make it easy for you, here's a link to
each module that was changed, in order:
1/18 acpi
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#acpi
2/18 authz
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#user-authorization
3/18 block
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#block-devices
4/18 crypto
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#cryptography-devices
5/18 dump
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#dump-guest-memory
6/18 job
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#background-jobs
7/18 machine
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#machines
8/18 migration
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#migration
9/18 net
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#net-devices
10/18 pci
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#pci
11/18 QOM
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#qemu-object-model-qom
12/18 replay
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#record-replay
13/18 run-state
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#vm-run-state
14/18 sockets
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#socket-data-types
15/18 ui
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#remote-desktop
16/18 virtio
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#virtio-devices
17/18 yank
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#yank-feature
18/18 misc
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#qmp-monitor-control
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#ebpf-objects
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#qmp-introspection
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-misc-arm
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-misc-i386
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-misc
https://jsnow.gitlab.io/qemu/interop/qemu-qmp-ref.html#module-QMP-stats
A few benefits of doing this:
(1) It makes the docs easier to navigate for users, being able to just
click to the referred data type / enum / event / command / etc.
(2) It helps prevent bitrot: if the name of a command / event / data
type / etc changes, the cross-reference will cause the build to
fail, giving a needed hint that documentation elsewhere needs to be
updated.
(3) Prompting the maintainers to review the generated HTML documentation
O:-)
A few hints for maintainers should they wish to try their own hand at
improving the documentation for their subsystems:
* Try building docs from your build directory like this:
> DEBUG=1 pyvenv/bin/sphinx-build -v -j 1 -b html -d docs/manual.p/
../docs/ docs/manual/;
Limiting to one thread makes sphinx errors more verbose (and
helpful), and if you run into rST formatting errors, you can view
the 'qapi_qapi-schema.ir' artifact in the build directory (DEBUG=1
causes this to exist) to examine the intermediate rST source code so
you don't have to fight with the QAPI parsing subsystem to
understand what happened.
* html docs of interest will be in
docs/manual/interop/qemu-qmp-ref.html
* QMP reference index will be at docs/manual/qapi-qmp-index.html
* QAPI-specific cross-referencing syntax is documented at
https://www.qemu.org/docs/master/devel/qapi-domain.html#cross-references
* QMP Example syntax is documented towards the bottom of this QAPI
codegen section:
https://www.qemu.org/docs/master/devel/qapi-code-gen.html#definition-documentation
John Snow (18):
qapi: add cross-references to acpi.json
qapi: add cross-references to authz.json
qapi: add cross-references to block layer
qapi: add cross-references to crypto.json
qapi: add cross-references to dump.json
qapi: add cross-references to job.json
qapi: add cross-references to Machine core
qapi: add cross-references to migration.json
qapi: add cross-references to net.json
qapi: add cross-references to pci.json
qapi: add cross-references to QOM
qapi: add cross-references to replay.json
qapi: add cross-references to run-state.json
qapi: add cross-references to sockets.json
qapi: add cross-references to ui.json
qapi: add cross-references to virtio.json
qapi: add cross-references to yank.json
qapi: add cross-references to misc modules
qapi/acpi.json | 2 +-
qapi/authz.json | 2 +-
qapi/block-core.json | 186 +++++++++++++++++++--------------------
qapi/block-export.json | 36 ++++----
qapi/block.json | 14 +--
qapi/control.json | 2 +-
qapi/crypto.json | 4 +-
qapi/dump.json | 10 +--
qapi/ebpf.json | 2 +-
qapi/introspect.json | 22 ++---
qapi/job.json | 73 +++++++--------
qapi/machine-common.json | 20 ++---
qapi/machine.json | 100 ++++++++++-----------
qapi/migration.json | 62 ++++++-------
qapi/misc-arm.json | 4 +-
qapi/misc-i386.json | 2 +-
qapi/misc.json | 6 +-
qapi/net.json | 4 +-
qapi/pci.json | 2 +-
qapi/qdev.json | 4 +-
qapi/qom.json | 9 +-
qapi/replay.json | 10 +--
qapi/run-state.json | 42 ++++-----
qapi/sockets.json | 6 +-
qapi/stats.json | 8 +-
qapi/transaction.json | 20 ++---
qapi/ui.json | 34 +++----
qapi/virtio.json | 8 +-
qapi/yank.json | 20 ++---
29 files changed, 358 insertions(+), 356 deletions(-)
--
2.48.1
