[PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[John Snow]

Add a new anchor to qmp-spec that allows us to cross-reference the
Out-of-band execution section of the spec directly.

Amend the documentation in qapi/control.json to use this new cross
reference instead of a plaintext "see also".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/interop/qmp-spec.rst | 2 ++
 qapi/control.json         | 3 +--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst
index 563344160e6..ea713a96ac0 100644
--- a/docs/interop/qmp-spec.rst
+++ b/docs/interop/qmp-spec.rst
@@ -119,6 +119,8 @@ Where:
 
 The actual commands are documented in the :doc:`qemu-qmp-ref`.
 
+.. _out-of-band execution:
+
 Out-of-band execution
 ---------------------
 
diff --git a/qapi/control.json b/qapi/control.json
index ef63a8a261b..e97fe317af7 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -44,8 +44,7 @@
 #     client connection, used for agreeing on particular QMP extension
 #     behaviors.
 #
-# @oob: QMP ability to support out-of-band requests.  (Please refer to
-#     qmp-spec.rst for more information on OOB)
+# @oob: QMP ability to support :ref:`out-of-band execution` requests.
 #
 # Since: 2.12
 ##
-- 
2.55.0

Re: [PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[Eric Blake]

On Tue, Sep 29, 2026 at 03:24:03PM -0400, John Snow wrote:
> Add a new anchor to qmp-spec that allows us to cross-reference the
> Out-of-band execution section of the spec directly.
> 
> Amend the documentation in qapi/control.json to use this new cross
> reference instead of a plaintext "see also".
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/interop/qmp-spec.rst | 2 ++
>  qapi/control.json         | 3 +--
>  2 files changed, 3 insertions(+), 2 deletions(-)

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[John Snow]

On Tue, Sep 29, 2026 at 3:24 PM John Snow <jsnow@redhat.com> wrote:
>
> Add a new anchor to qmp-spec that allows us to cross-reference the
> Out-of-band execution section of the spec directly.
>
> Amend the documentation in qapi/control.json to use this new cross
> reference instead of a plaintext "see also".
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> Signed-off-by: John Snow <jsnow@redhat.com>

Markus: With no feedback, I assume this is good to go?

> ---
>  docs/interop/qmp-spec.rst | 2 ++
>  qapi/control.json         | 3 +--
>  2 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst
> index 563344160e6..ea713a96ac0 100644
> --- a/docs/interop/qmp-spec.rst
> +++ b/docs/interop/qmp-spec.rst
> @@ -119,6 +119,8 @@ Where:
>
>  The actual commands are documented in the :doc:`qemu-qmp-ref`.
>
> +.. _out-of-band execution:
> +
>  Out-of-band execution
>  ---------------------
>
> diff --git a/qapi/control.json b/qapi/control.json
> index ef63a8a261b..e97fe317af7 100644
> --- a/qapi/control.json
> +++ b/qapi/control.json
> @@ -44,8 +44,7 @@
>  #     client connection, used for agreeing on particular QMP extension
>  #     behaviors.
>  #
> -# @oob: QMP ability to support out-of-band requests.  (Please refer to
> -#     qmp-spec.rst for more information on OOB)
> +# @oob: QMP ability to support :ref:`out-of-band execution` requests.
>  #
>  # Since: 2.12
>  ##
> --
> 2.55.0
>

Re: [PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Tue, Sep 29, 2026 at 3:24 PM John Snow <jsnow@redhat.com> wrote:
>>
>> Add a new anchor to qmp-spec that allows us to cross-reference the
>> Out-of-band execution section of the spec directly.
>>
>> Amend the documentation in qapi/control.json to use this new cross
>> reference instead of a plaintext "see also".
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> Signed-off-by: John Snow <jsnow@redhat.com>
>
> Markus: With no feedback, I assume this is good to go?

Queued.  Thanks!

[PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/control.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/control.json b/qapi/control.json
index 9898552814..c56aabacff 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -46,7 +46,7 @@
 # connection, used for agreeing on particular QMP extension behaviors.
 #
 # @oob: QMP ability to support out-of-band requests.  (Please refer to
-#     qmp-spec.rst for more information on OOB)
+#     :doc:`/interop/qmp-spec` for more information on OOB)
 #
 # Since: 2.12
 ##
-- 
2.55.0

Re: [PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[John Snow]

On Mon, Sep 28, 2026 at 2:32 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/control.json | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/qapi/control.json b/qapi/control.json
> index 9898552814..c56aabacff 100644
> --- a/qapi/control.json
> +++ b/qapi/control.json
> @@ -46,7 +46,7 @@
>  # connection, used for agreeing on particular QMP extension behaviors.
>  #
>  # @oob: QMP ability to support out-of-band requests.  (Please refer to
> -#     qmp-spec.rst for more information on OOB)
> +#     :doc:`/interop/qmp-spec` for more information on OOB)
>  #
>  # Since: 2.12
>  ##
> --
> 2.55.0
>

I have a similar patch coming up in my rework of the @oob feature that:

(1) Adds an anchor to the OOB section of the qmp spec explicitly,
(2) Uses a standard form text with the above reference when generating
docs for commands with the @oob property.

The second doesn't apply to this command as it's an arg and not a
feature/property; but we can do better and link directly to the OOB
section of the spec doc.

--js

Re: [PATCH] qapi/control: Turn the reference to qmp-spec.rst into a link

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Mon, Sep 28, 2026 at 2:32 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  qapi/control.json | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/qapi/control.json b/qapi/control.json
>> index 9898552814..c56aabacff 100644
>> --- a/qapi/control.json
>> +++ b/qapi/control.json
>> @@ -46,7 +46,7 @@
>>  # connection, used for agreeing on particular QMP extension behaviors.
>>  #
>>  # @oob: QMP ability to support out-of-band requests.  (Please refer to
>> -#     qmp-spec.rst for more information on OOB)
>> +#     :doc:`/interop/qmp-spec` for more information on OOB)
>>  #
>>  # Since: 2.12
>>  ##
>> --
>> 2.55.0
>>
>
> I have a similar patch coming up in my rework of the @oob feature that:
>
> (1) Adds an anchor to the OOB section of the qmp spec explicitly,
> (2) Uses a standard form text with the above reference when generating
> docs for commands with the @oob property.
>
> The second doesn't apply to this command as it's an arg and not a
> feature/property; but we can do better and link directly to the OOB
> section of the spec doc.

I'm glad I cc'ed you.  Would you like me to drop this patch?  Or should
I merge it, and you improve on top?