Skip to content

QAPI: add cross-references to qapi docs

John Snow qemu-devel 2 versions – Applied

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

  1. v2 Latest18 patches 9 repliesApplied
  2. 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 filesSizeRepliesApplied
1/18qapi: add cross-references to acpi.jsonqapi/acpi.json+1 -10 replies
2/18qapi: add cross-references to authz.jsonqapi/authz.json+1 -10 replies
3/18qapi: add cross-references to block layerqapi/block-core.json qapi/block-export.json qapi/block.json +1 more+125 -1251 reply
4/18qapi: add cross-references to crypto.jsonqapi/crypto.json+2 -21 reply
5/18qapi: add cross-references to dump.jsonqapi/dump.json+6 -60 replies
6/18qapi: add cross-references to job.jsonqapi/job.json+36 -351 reply
7/18qapi: add cross-references to Machine coreqapi/machine-common.json qapi/machine.json+51 -510 replies
8/18qapi: add cross-references to migration.jsonqapi/migration.json+34 -342 replies
9/18qapi: add cross-references to net.jsonqapi/net.json+3 -30 replies
10/18qapi: add cross-references to pci.jsonqapi/pci.json+1 -10 replies
11/18qapi: add cross-references to QOMqapi/qdev.json qapi/qom.json+9 -80 replies
12/18qapi: add cross-references to replay.jsonqapi/replay.json+5 -50 replies
13/18qapi: add cross-references to run-state.jsonqapi/run-state.json+23 -230 replies
14/18qapi: add cross-references to sockets.jsonqapi/sockets.json+3 -30 replies
15/18qapi: add cross-references to ui.jsonqapi/ui.json+17 -170 replies
16/18qapi: add cross-references to virtio.jsonqapi/virtio.json+4 -40 replies
17/18qapi: add cross-references to yank.jsonqapi/yank.json+8 -80 replies
18/18qapi: add cross-references to misc modulesqapi/control.json qapi/ebpf.json qapi/introspect.json +4 more+27 -270 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.

PatchLukas StraubEric BlakeMarkus Armbruster
SeriesR-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/18R-b
15/18
16/18
17/18A-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.

Read the v2 thread

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