[PATCH v2 00/18] QAPI: add cross-references to qapi docs

[John Snow <jsnow@redhat.com>]

Based-on: 20250711051045.51110-1-jsnow@redhat.com
    [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:
    > 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(-)

-- 
2.50.0