From 25d44f57e17b088fdc4e38042e04c4e9da2c1088 Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:09 -0400 Subject: docs/qapi-domain: add namespaced index support Generate an index-per-namespace for the QAPI domain. Due to a limitation with Sphinx's architecture, these indices must be defined during setup time and cannot be dynamically created on-demand when a namespace directive is encountered. Owing to that limitation, add a configuration value to conf.py that specifies which QAPI namespaces we'll generate indices for. Indices will be named after their namespace, e.g. the "QMP" namespace will generate to "qapi-qmp-index.html" and can be referenced using `qapi-qmp-index`. Signed-off-by: John Snow Message-ID: <20250313044312.189276-9-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index a3f9fa63d9..175491148c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -161,6 +161,9 @@ qapi_allowed_fields = { "see also", } +# Due to a limitation in Sphinx, we need to know which indices to +# generate in advance. Adding a namespace here allows that generation. +qapi_namespaces = set() # -- Options for HTML output ---------------------------------------------- -- cgit 1.4.1 From 602c90beaedd9abbbf1535c8630293267e6b29c0 Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:10 -0400 Subject: docs: add QAPI namespace "QMP" to qemu-qmp-ref This also creates the qapi-qmp-index.html index and cross-reference target. Signed-off-by: John Snow Message-ID: <20250313044312.189276-10-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/conf.py | 4 +++- docs/interop/qemu-qmp-ref.rst | 1 + qapi/qapi-schema.json | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index 175491148c..9a86e84a80 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -163,7 +163,9 @@ qapi_allowed_fields = { # Due to a limitation in Sphinx, we need to know which indices to # generate in advance. Adding a namespace here allows that generation. -qapi_namespaces = set() +qapi_namespaces = { + "QMP", +} # -- Options for HTML output ---------------------------------------------- diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index e95eeac45e..ef8792b53f 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -8,3 +8,4 @@ QEMU QMP Reference Manual .. qapi-doc:: qapi/qapi-schema.json :transmogrify: + :namespace: QMP diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 4475e81cc3..c41c01eb2a 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -5,7 +5,7 @@ # # This document describes all commands currently supported by QMP. # -# For locating a particular item, please see the `qapi-index`. +# For locating a particular item, please see the `qapi-qmp-index`. # # Most of the time their usage is exactly the same as in the user # Monitor, this means that any other document which also describe -- cgit 1.4.1 From a6af54434400099b8afd59ba036cf9a662006d1e Mon Sep 17 00:00:00 2001 From: John Snow Date: Thu, 13 Mar 2025 00:43:12 -0400 Subject: docs: enable transmogrifier for QSD and QGA This also creates the `qapi-qsd-index` and `qapi-qga-index` QMP indices. Signed-off-by: John Snow Message-ID: <20250313044312.189276-12-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/conf.py | 2 ++ docs/interop/qemu-ga-ref.rst | 2 ++ docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 ++ qga/qapi-schema.json | 3 +++ storage-daemon/qapi/qapi-schema.json | 8 ++++++++ 5 files changed, 17 insertions(+) (limited to 'docs/conf.py') diff --git a/docs/conf.py b/docs/conf.py index 9a86e84a80..7b5712e122 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -164,7 +164,9 @@ qapi_allowed_fields = { # Due to a limitation in Sphinx, we need to know which indices to # generate in advance. Adding a namespace here allows that generation. qapi_namespaces = { + "QGA", "QMP", + "QSD", } # -- Options for HTML output ---------------------------------------------- diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 032d492455..19b5c7a549 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -5,3 +5,5 @@ QEMU Guest Agent Protocol Reference :depth: 3 .. qapi-doc:: qga/qapi-schema.json + :transmogrify: + :namespace: QGA diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index 9fed68152f..d0228d63b8 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -5,3 +5,5 @@ QEMU Storage Daemon QMP Reference Manual :depth: 3 .. qapi-doc:: storage-daemon/qapi/qapi-schema.json + :transmogrify: + :namespace: QSD diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 995594aaf4..35ec0e7db3 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -3,6 +3,9 @@ ## # = QEMU guest agent protocol commands and structs +# +# For a concise listing of all commands, events, and types in the QEMU +# guest agent, please consult the `qapi-qga-index`. ## { 'pragma': { 'doc-required': true } } diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json index f10c949490..2a562ee32e 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -13,6 +13,14 @@ # the array type in the main schema, even if it is unused outside of the # storage daemon. +## +# = QEMU storage daemon protocol commands and structs +# +# For a concise listing of all commands, events, and types in the QEMU +# storage daemon, please consult the `qapi-qsd-index`. +## + + { 'include': '../../qapi/pragma.json' } # Documentation generated with qapi-gen.py is in source order, with -- cgit 1.4.1