QAPI: add cross-references to qapi docs
Status from this message: Queued for 10.1. Thanks!
Get series with b4
b4 am [email protected]Versions newest first · linked by author and title
- v2 Latest18 patches 9 repliesApplied
- v118 patches 12 repliesSuperseded
Changes in v2 from the cover letter
- Applied a few new transformations I had missed.
- Manually excluded those Markus pointed out as being unhelpful.
Patches in v2 Applied
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/18 | qapi: add cross-references to acpi.jsonqapi/ | +1 | 0 replies | |
| 2/18 | qapi: add cross-references to authz.jsonqapi/ | +1 | 0 replies | |
| 3/18 | qapi: add cross-references to block layerqapi/ qapi/ qapi/ +1 more | +125 | 1 reply | |
| 4/18 | qapi: add cross-references to crypto.jsonqapi/ | +2 | 1 reply | |
| 5/18 | qapi: add cross-references to dump.jsonqapi/ | +6 | 0 replies | |
| 6/18 | qapi: add cross-references to job.jsonqapi/ | +36 | 1 reply | |
| 7/18 | qapi: add cross-references to Machine coreqapi/ qapi/ | +51 | 0 replies | |
| 8/18 | qapi: add cross-references to migration.jsonqapi/ | +34 | 2 replies | |
| 9/18 | qapi: add cross-references to net.jsonqapi/ | +3 | 0 replies | |
| 10/18 | qapi: add cross-references to pci.jsonqapi/ | +1 | 0 replies | |
| 11/18 | qapi: add cross-references to QOMqapi/ qapi/ | +9 | 0 replies | |
| 12/18 | qapi: add cross-references to replay.jsonqapi/ | +5 | 0 replies | |
| 13/18 | qapi: add cross-references to run-state.jsonqapi/ | +23 | 0 replies | |
| 14/18 | qapi: add cross-references to sockets.jsonqapi/ | +3 | 0 replies | |
| 15/18 | qapi: add cross-references to ui.jsonqapi/ | +17 | 0 replies | |
| 16/18 | qapi: add cross-references to virtio.jsonqapi/ | +4 | 0 replies | |
| 17/18 | qapi: add cross-references to yank.jsonqapi/ | +8 | 0 replies | |
| 18/18 | qapi: add cross-references to misc modulesqapi/ qapi/ qapi/ +4 more | +27 | 0 replies |
Reviews trailers per patch
2 of 18 patches have a Reviewed-by or Acked-by of their own; the series has one for all of them.
| Patch | Lukas Straub | Eric Blake | Markus Armbruster |
|---|---|---|---|
| Series | R-b | ||
| 1/18 | |||
| 2/18 | |||
| 3/18 | |||
| 4/18 | |||
| 5/18 | |||
| 6/18 | |||
| 7/18 | |||
| 8/18 | |||
| 9/18 | |||
| 10/18 | |||
| 11/18 | |||
| 12/18 | |||
| 13/18 | |||
| 14/18 | R-b | ||
| 15/18 | |||
| 16/18 | |||
| 17/18 | A-b | ||
| 18/18 |
Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 3 reviewers.
Cover letter [PATCH v2 00/18] QAPI: add cross-references to qapi docs
Based-on: [email protected]
[PATCH v6 0/4] qapi: add auto-generated return docs
v2:
- Applied a few new transformations I had missed.
- Manually excluded those Markus pointed out as being unhelpful.
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:
Quoted 1 line
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 | 188 +++++++++++++++++++-------------------- qapi/block-export.json | 36 ++++---- qapi/block.json | 14 +-- qapi/control.json | 2 +- qapi/crypto.json | 4 +- qapi/dump.json | 12 +-- qapi/ebpf.json | 2 +- qapi/introspect.json | 24 ++--- qapi/job.json | 71 +++++++-------- qapi/machine-common.json | 20 ++--- qapi/machine.json | 82 ++++++++--------- qapi/migration.json | 68 +++++++------- qapi/misc-arm.json | 4 +- qapi/misc-i386.json | 2 +- qapi/misc.json | 12 +-- qapi/net.json | 6 +- qapi/pci.json | 2 +- qapi/qdev.json | 4 +- qapi/qom.json | 13 +-- qapi/replay.json | 10 +-- qapi/run-state.json | 46 +++++----- qapi/sockets.json | 6 +- qapi/stats.json | 8 +- qapi/transaction.json | 12 +-- qapi/ui.json | 34 +++---- qapi/virtio.json | 8 +- qapi/yank.json | 16 ++-- 29 files changed, 356 insertions(+), 354 deletions(-)
Signature · 1 line
2.50.0