[PATCH v3 0/5] docs: remove legacy qapidoc

John Snow posted 5 patches 4 months, 4 weeks ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20250618165353.1980365-1-jsnow@redhat.com
Maintainers: Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, "Daniel P. Berrangé" <berrange@redhat.com>, Kashyap Chamarthy <kchamart@redhat.com>, Kostiantyn Kostiuk <kkostiuk@redhat.com>, Kevin Wolf <kwolf@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, Stefano Garzarella <sgarzare@redhat.com>, John Snow <jsnow@redhat.com>, Peter Maydell <peter.maydell@linaro.org>, Cleber Rosa <crosa@redhat.com>, Eric Blake <eblake@redhat.com>, Igor Mammedov <imammedo@redhat.com>, Ani Sinha <anisinha@redhat.com>, Gerd Hoffmann <kraxel@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Gonglei (Arei)" <arei.gonglei@huawei.com>, Zhenwei Pi <pizhenwei@bytedance.com>, Jonathan Cameron <jonathan.cameron@huawei.com>, Fan Ni <fan.ni@samsung.com>, Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, Yanan Wang <wangyanan55@huawei.com>, Zhao Liu <zhao1.liu@intel.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Jiri Pirko <jiri@resnulli.us>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Stefan Hajnoczi <stefanha@redhat.com>, Mads Ynddal <mads@ynddal.dk>, Alex Williamson <alex.williamson@redhat.com>, "Cédric Le Goater" <clg@redhat.com>, Lukas Straub <lukasstraub2@web.de>
docs/devel/qapi-code-gen.rst                 |  28 +-
docs/interop/firmware.json                   |   4 +-
docs/interop/qemu-ga-ref.rst                 |   1 -
docs/interop/qemu-qmp-ref.rst                |   1 -
docs/interop/qemu-storage-daemon-qmp-ref.rst |   1 -
docs/interop/vhost-user.json                 |   4 +-
docs/sphinx/qapidoc.py                       |  82 +---
docs/sphinx/qapidoc_legacy.py                | 440 -------------------
qapi/acpi.json                               |   4 +-
qapi/audio.json                              |   4 +-
qapi/authz.json                              |   4 +-
qapi/block-core.json                         |   3 +-
qapi/block-export.json                       |   3 +-
qapi/block.json                              |   7 +-
qapi/char.json                               |   4 +-
qapi/common.json                             |   4 +-
qapi/compat.json                             |   4 +-
qapi/control.json                            |   4 +-
qapi/crypto.json                             |   4 +-
qapi/cryptodev.json                          |   4 +-
qapi/cxl.json                                |   4 +-
qapi/dump.json                               |   4 +-
qapi/ebpf.json                               |   4 +-
qapi/error.json                              |   4 +-
qapi/introspect.json                         |   4 +-
qapi/job.json                                |   4 +-
qapi/machine-common.json                     |   4 +-
qapi/machine.json                            |   4 +-
qapi/migration.json                          |   4 +-
qapi/misc.json                               |   4 +-
qapi/net.json                                |   4 +-
qapi/pci.json                                |   4 +-
qapi/qapi-schema.json                        |   4 +-
qapi/qdev.json                               |   4 +-
qapi/qom.json                                |   4 +-
qapi/replay.json                             |   4 +-
qapi/rocker.json                             |   4 +-
qapi/run-state.json                          |   4 +-
qapi/sockets.json                            |   4 +-
qapi/stats.json                              |   4 +-
qapi/tpm.json                                |   4 +-
qapi/trace.json                              |   4 +-
qapi/transaction.json                        |   4 +-
qapi/uefi.json                               |   4 +-
qapi/ui.json                                 |  14 +-
qapi/vfio.json                               |   4 +-
qapi/virtio.json                             |   4 +-
qapi/yank.json                               |   4 +-
python/tests/qapi-isort.sh                   |   2 +-
scripts/qapi/parser.py                       |  11 -
storage-daemon/qapi/qapi-schema.json         |   8 +-
tests/qapi-schema/doc-bad-section.err        |   1 -
tests/qapi-schema/doc-bad-section.json       |  10 -
tests/qapi-schema/doc-bad-section.out        |   0
tests/qapi-schema/doc-good.json              |  10 +-
tests/qapi-schema/doc-good.out               |  10 +-
tests/qapi-schema/doc-good.txt               | 274 ++++--------
tests/qapi-schema/meson.build                |   1 -
58 files changed, 275 insertions(+), 784 deletions(-)
delete mode 100644 docs/sphinx/qapidoc_legacy.py
delete mode 100644 tests/qapi-schema/doc-bad-section.err
delete mode 100644 tests/qapi-schema/doc-bad-section.json
delete mode 100644 tests/qapi-schema/doc-bad-section.out
[PATCH v3 0/5] docs: remove legacy qapidoc
Posted by John Snow 4 months, 4 weeks ago
Remove docs/sphinx/qapidoc_legacy.py, and remove special parsing of
freeform QAPI documentation block sections in favor of using standard
rST syntax that is included in the final document with no special
parsing or post-processing.

v3:
 - Fixed indentation for :error: in qapidoc
 - Removed parser restrictions on QAPI-style headers
 - Updated test output so make check passes ...

v2:
 - rebased on origin/master (2025-06-12)
 - Revised commit messages with increased detail

John Snow (5):
  docs/sphinx: adjust qapidoc to cope with same-line error sections
  docs/sphinx: parse @references in freeform text
  docs/sphinx: remove legacy QAPI manual generator
  docs/sphinx: remove special parsing for freeform sections
  qapi: lift restriction on using '=' in doc blocks

 docs/devel/qapi-code-gen.rst                 |  28 +-
 docs/interop/firmware.json                   |   4 +-
 docs/interop/qemu-ga-ref.rst                 |   1 -
 docs/interop/qemu-qmp-ref.rst                |   1 -
 docs/interop/qemu-storage-daemon-qmp-ref.rst |   1 -
 docs/interop/vhost-user.json                 |   4 +-
 docs/sphinx/qapidoc.py                       |  82 +---
 docs/sphinx/qapidoc_legacy.py                | 440 -------------------
 qapi/acpi.json                               |   4 +-
 qapi/audio.json                              |   4 +-
 qapi/authz.json                              |   4 +-
 qapi/block-core.json                         |   3 +-
 qapi/block-export.json                       |   3 +-
 qapi/block.json                              |   7 +-
 qapi/char.json                               |   4 +-
 qapi/common.json                             |   4 +-
 qapi/compat.json                             |   4 +-
 qapi/control.json                            |   4 +-
 qapi/crypto.json                             |   4 +-
 qapi/cryptodev.json                          |   4 +-
 qapi/cxl.json                                |   4 +-
 qapi/dump.json                               |   4 +-
 qapi/ebpf.json                               |   4 +-
 qapi/error.json                              |   4 +-
 qapi/introspect.json                         |   4 +-
 qapi/job.json                                |   4 +-
 qapi/machine-common.json                     |   4 +-
 qapi/machine.json                            |   4 +-
 qapi/migration.json                          |   4 +-
 qapi/misc.json                               |   4 +-
 qapi/net.json                                |   4 +-
 qapi/pci.json                                |   4 +-
 qapi/qapi-schema.json                        |   4 +-
 qapi/qdev.json                               |   4 +-
 qapi/qom.json                                |   4 +-
 qapi/replay.json                             |   4 +-
 qapi/rocker.json                             |   4 +-
 qapi/run-state.json                          |   4 +-
 qapi/sockets.json                            |   4 +-
 qapi/stats.json                              |   4 +-
 qapi/tpm.json                                |   4 +-
 qapi/trace.json                              |   4 +-
 qapi/transaction.json                        |   4 +-
 qapi/uefi.json                               |   4 +-
 qapi/ui.json                                 |  14 +-
 qapi/vfio.json                               |   4 +-
 qapi/virtio.json                             |   4 +-
 qapi/yank.json                               |   4 +-
 python/tests/qapi-isort.sh                   |   2 +-
 scripts/qapi/parser.py                       |  11 -
 storage-daemon/qapi/qapi-schema.json         |   8 +-
 tests/qapi-schema/doc-bad-section.err        |   1 -
 tests/qapi-schema/doc-bad-section.json       |  10 -
 tests/qapi-schema/doc-bad-section.out        |   0
 tests/qapi-schema/doc-good.json              |  10 +-
 tests/qapi-schema/doc-good.out               |  10 +-
 tests/qapi-schema/doc-good.txt               | 274 ++++--------
 tests/qapi-schema/meson.build                |   1 -
 58 files changed, 275 insertions(+), 784 deletions(-)
 delete mode 100644 docs/sphinx/qapidoc_legacy.py
 delete mode 100644 tests/qapi-schema/doc-bad-section.err
 delete mode 100644 tests/qapi-schema/doc-bad-section.json
 delete mode 100644 tests/qapi-schema/doc-bad-section.out

-- 
2.48.1

Re: [PATCH v3 0/5] docs: remove legacy qapidoc
Posted by Markus Armbruster 4 months ago
John Snow <jsnow@redhat.com> writes:

> Remove docs/sphinx/qapidoc_legacy.py, and remove special parsing of
> freeform QAPI documentation block sections in favor of using standard
> rST syntax that is included in the final document with no special
> parsing or post-processing.

PATCH 1-3
Acked-by: Markus Armbruster <armbru@redhat.com>

PATCH 4+5
Reviewed-by: Markus Armbruster <armbru@redhat.com>

Queued, thanks!