From patchwork Wed Jul 3 21:01:36 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722777 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id C1BD1C3271E for ; Wed, 3 Jul 2024 21:03:14 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77B-0000eX-Tz; Wed, 03 Jul 2024 17:02:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77A-0000eB-CJ for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:08 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP778-00089O-OQ for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:08 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040526; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=weZkuUwuyqy4MTMy3EjAIkediRMFFXVHhEi2kP2UMqs=; b=Dl6OmrnJCyLfciaVhhZJcVEkXAqaVwauYkhhyf+cxv4n4YsWf8FsgEJHwm8E55saE/0G1w CUd4LxeGQxvVS8qnKppHM2XvzwG3d74ZNmJDGHiJ6cxMDo3wQi70GPVDfsXZeaHqMH9IEU OpRv26l/QjiK/4rVlsuDNEKqgLcY4W8= Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-571-VPASe2OdMOiGj2M1tf2iBA-1; Wed, 03 Jul 2024 17:02:02 -0400 X-MC-Unique: VPASe2OdMOiGj2M1tf2iBA-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 6C8C3195608C; Wed, 3 Jul 2024 21:02:00 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1A29F1955F22; Wed, 3 Jul 2024 21:01:53 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 1/8] docs/qapidoc: factor out do_parse() Date: Wed, 3 Jul 2024 17:01:36 -0400 Message-ID: <20240703210144.339530-2-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Factor out the compatibility parser helper into a base class, so it can be shared by other directives. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 64 +++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index efcd84656fa..43dd99e21e6 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -494,7 +494,41 @@ def visit_module(self, name): super().visit_module(name) -class QAPIDocDirective(Directive): +class NestedDirective(Directive): + def run(self): + raise NotImplementedError + + def do_parse(self, rstlist, node): + """ + Parse rST source lines and add them to the specified node + + Take the list of rST source lines rstlist, parse them as + rST, and add the resulting docutils nodes as children of node. + The nodes are parsed in a way that allows them to include + subheadings (titles) without confusing the rendering of + anything else. + """ + # This is from kerneldoc.py -- it works around an API change in + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use + # sphinx.util.nodes.nested_parse_with_titles() rather than the + # plain self.state.nested_parse(), and so we can drop the saving + # of title_styles and section_level that kerneldoc.py does, + # because nested_parse_with_titles() does that for us. + if USE_SSI: + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + else: + save = self.state.memo.reporter + self.state.memo.reporter = AutodocReporter( + rstlist, self.state.memo.reporter + ) + try: + nested_parse_with_titles(self.state, rstlist, node) + finally: + self.state.memo.reporter = save + + +class QAPIDocDirective(NestedDirective): """Extract documentation from the specified QAPI .json file""" required_argument = 1 @@ -532,34 +566,6 @@ def run(self): # so they are displayed nicely to the user raise ExtensionError(str(err)) from err - def do_parse(self, rstlist, node): - """Parse rST source lines and add them to the specified node - - Take the list of rST source lines rstlist, parse them as - rST, and add the resulting docutils nodes as children of node. - The nodes are parsed in a way that allows them to include - subheadings (titles) without confusing the rendering of - anything else. - """ - # This is from kerneldoc.py -- it works around an API change in - # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use - # sphinx.util.nodes.nested_parse_with_titles() rather than the - # plain self.state.nested_parse(), and so we can drop the saving - # of title_styles and section_level that kerneldoc.py does, - # because nested_parse_with_titles() does that for us. - if USE_SSI: - with switch_source_input(self.state, rstlist): - nested_parse_with_titles(self.state, rstlist, node) - else: - save = self.state.memo.reporter - self.state.memo.reporter = AutodocReporter( - rstlist, self.state.memo.reporter - ) - try: - nested_parse_with_titles(self.state, rstlist, node) - finally: - self.state.memo.reporter = save - def setup(app): """Register qapi-doc directive with Sphinx""" From patchwork Wed Jul 3 21:01:37 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722780 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 9CC3FC2BD09 for ; Wed, 3 Jul 2024 21:03:24 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77K-0000gl-Pj; Wed, 03 Jul 2024 17:02:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77J-0000g3-14 for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:17 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77F-0008Pf-U9 for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:16 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040533; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=cxl7x8qPtOxUovBAEtH6UY8PdMbh86nXRDO+5jHQ2Kg=; b=PTp5gVwOwTWNibgC5YtsXYS4xEaPA44FPuyaGK7Ilu8DqQL+5gU0nlp1uDC7SAY4eEhoGV bUd6J1oeM2Vn2CbLjxYnFxw8RbwXXYxcrUAmGfS7NA517d+gbyn2JrmE3T1LmrqomaaSqu Um0u2AtKK1TMx9bVkKO60Rf5RkwpfPg= Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-146-mUr1NBusO8SiIkxtokZTcQ-1; Wed, 03 Jul 2024 17:02:10 -0400 X-MC-Unique: mUr1NBusO8SiIkxtokZTcQ-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 86BE01954B17; Wed, 3 Jul 2024 21:02:07 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id CFA821955F21; Wed, 3 Jul 2024 21:02:00 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 2/8] docs/qapidoc: create qmp-example directive Date: Wed, 3 Jul 2024 17:01:37 -0400 Message-ID: <20240703210144.339530-3-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org This is a directive that creates a syntactic sugar for creating "Example" boxes very similar to the ones already used in the bitmaps.rst document, please see e.g. https://www.qemu.org/docs/master/interop/bitmaps.html#creation-block-dirty-bitmap-add In its simplest form, when a custom title is not needed or wanted, and the example body is *solely* a QMP example: ``` .. qmp-example:: {body} ``` is syntactic sugar for: ``` .. admonition:: Example: .. code-block:: QMP {body} ``` When a custom, plaintext title that describes the example is desired, this form: ``` .. qmp-example:: :title: Defrobnification {body} ``` Is syntactic sugar for: ``` .. admonition:: Example: Defrobnification .. code-block:: QMP {body} ``` Lastly, when Examples are multi-step processes that require non-QMP exposition, have lengthy titles, or otherwise involve prose with rST markup (lists, cross-references, etc), the most complex form: ``` .. qmp-example:: :annotated: This example shows how to use `foo-command`:: {body} For more information, please see `frobnozz`. ``` Is desugared to: ``` .. admonition:: Example: This example shows how to use `foo-command`:: {body} For more information, please see `frobnozz`. ``` Note that :annotated: and :title: options can be combined together, if desired. The primary benefit here being documentation source consistently using the same directive for all forms of examples to ensure consistent visual styling, and ensuring all relevant prose is visually grouped alongside the code literal block. Note that as of this commit, the code-block rST syntax "::" does not apply QMP highlighting; you would need to use ".. code-block:: QMP". The very next commit changes this behavior to assume all "::" code blocks within this directive are QMP blocks. Signed-off-by: John Snow Acked-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 55 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 43dd99e21e6..b0f3917dc5b 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -27,6 +27,7 @@ import os import re import textwrap +from typing import List from docutils import nodes from docutils.parsers.rst import Directive, directives @@ -36,6 +37,7 @@ from qapi.schema import QAPISchema import sphinx +from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError from sphinx.util.nodes import nested_parse_with_titles @@ -567,10 +569,63 @@ def run(self): raise ExtensionError(str(err)) from err +class QMPExample(CodeBlock, NestedDirective): + """ + Custom admonition for QMP code examples. + + When the :annotated: option is present, the body of this directive + is parsed as normal rST instead. Code blocks must be explicitly + written by the user, but this allows for intermingling explanatory + paragraphs with arbitrary rST syntax and code blocks for more + involved examples. + + When :annotated: is absent, the directive body is treated as a + simple standalone QMP code block literal. + """ + + required_argument = 0 + optional_arguments = 0 + has_content = True + option_spec = { + "annotated": directives.flag, + "title": directives.unchanged, + } + + def admonition_wrap(self, *content) -> List[nodes.Node]: + title = "Example:" + if "title" in self.options: + title = f"{title} {self.options['title']}" + + admon = nodes.admonition( + "", + nodes.title("", title), + *content, + classes=["admonition", "admonition-example"], + ) + return [admon] + + def run_annotated(self) -> List[nodes.Node]: + content_node: nodes.Element = nodes.section() + self.do_parse(self.content, content_node) + return content_node.children + + def run(self) -> List[nodes.Node]: + annotated = "annotated" in self.options + + if annotated: + content_nodes = self.run_annotated() + else: + self.arguments = ["QMP"] + content_nodes = super().run() + + return self.admonition_wrap(*content_nodes) + + def setup(app): """Register qapi-doc directive with Sphinx""" app.add_config_value("qapidoc_srctree", None, "env") app.add_directive("qapi-doc", QAPIDocDirective) + app.add_directive("qmp-example", QMPExample) return { "version": __version__, From patchwork Wed Jul 3 21:01:38 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722781 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 53276C2BD09 for ; Wed, 3 Jul 2024 21:03:43 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77Q-0000hg-7j; Wed, 03 Jul 2024 17:02:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77O-0000hJ-Lf for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:22 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77N-0000S0-0I for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:22 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040540; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=yjCSx2xXZa2imboFxKPWgPHy6sZtgdQlYu7Dkui4UnQ=; b=dhXpDxQEL4L7Ib5/D8IspCnKQocHpvLymNtpfgJZzCeziSj3OLoCUIcQMyfvOOmeC4I3Ho nNBCuZNQdPn7oT1e8ydiPMunf2qIWqxKueRLBd5vpXGsJItQvdcuHrZjTLAoXMI5I7J7x0 BvAxdfw2+zmL1VBNF5TQNai9+lkJOZg= Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-294-m6tCTfLVNk6e7JdkMKK5bA-1; Wed, 03 Jul 2024 17:02:16 -0400 X-MC-Unique: m6tCTfLVNk6e7JdkMKK5bA-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8EC4B1955F69; Wed, 3 Jul 2024 21:02:14 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B55FC1955F22; Wed, 3 Jul 2024 21:02:07 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 3/8] docs/qapidoc: add QMP highlighting to annotated qmp-example blocks Date: Wed, 3 Jul 2024 17:01:38 -0400 Message-ID: <20240703210144.339530-4-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org For any code literal blocks inside of a qmp-example directive, apply and enforce the QMP lexer/highlighter to those blocks. This way, you won't need to write: ``` .. qmp-example:: :annotated: Blah blah .. code-block:: QMP -> { "lorem": "ipsum" } ``` But instead, simply: ``` .. qmp-example:: :annotated: Blah blah:: -> { "lorem": "ipsum" } ``` Once the directive block is exited, whatever the previous default highlight language was will be restored; localizing the forced QMP lexing to exclusively this directive. Note, if the default language is *already* QMP, this directive will not generate and restore redundant highlight configuration nodes. We may well decide that the default language ought to be QMP for any QAPI reference pages, but this way the directive behaves consistently no matter where it is used. Signed-off-by: John Snow Acked-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 53 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index b0f3917dc5b..fb2b23698a0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -26,6 +26,7 @@ import os import re +import sys import textwrap from typing import List @@ -37,6 +38,7 @@ from qapi.schema import QAPISchema import sphinx +from sphinx import addnodes from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError from sphinx.util.nodes import nested_parse_with_titles @@ -574,10 +576,10 @@ class QMPExample(CodeBlock, NestedDirective): Custom admonition for QMP code examples. When the :annotated: option is present, the body of this directive - is parsed as normal rST instead. Code blocks must be explicitly - written by the user, but this allows for intermingling explanatory - paragraphs with arbitrary rST syntax and code blocks for more - involved examples. + is parsed as normal rST, but with any '::' code blocks set to use + the QMP lexer. Code blocks must be explicitly written by the user, + but this allows for intermingling explanatory paragraphs with + arbitrary rST syntax and code blocks for more involved examples. When :annotated: is absent, the directive body is treated as a simple standalone QMP code block literal. @@ -591,6 +593,33 @@ class QMPExample(CodeBlock, NestedDirective): "title": directives.unchanged, } + def _highlightlang(self) -> addnodes.highlightlang: + """Return the current highlightlang setting for the document""" + node = None + doc = self.state.document + + if hasattr(doc, "findall"): + # docutils >= 0.18.1 + for node in doc.findall(addnodes.highlightlang): + pass + else: + for elem in doc.traverse(): + if isinstance(elem, addnodes.highlightlang): + node = elem + + if node: + return node + + # No explicit directive found, use defaults + node = addnodes.highlightlang( + lang=self.env.config.highlight_language, + force=False, + # Yes, Sphinx uses this value to effectively disable line + # numbers and not 0 or None or -1 or something. ¯\_(ツ)_/¯ + linenothreshold=sys.maxsize, + ) + return node + def admonition_wrap(self, *content) -> List[nodes.Node]: title = "Example:" if "title" in self.options: @@ -605,8 +634,24 @@ def admonition_wrap(self, *content) -> List[nodes.Node]: return [admon] def run_annotated(self) -> List[nodes.Node]: + lang_node = self._highlightlang() + content_node: nodes.Element = nodes.section() + + # Configure QMP highlighting for "::" blocks, if needed + if lang_node["lang"] != "QMP": + content_node += addnodes.highlightlang( + lang="QMP", + force=False, # "True" ignores lexing errors + linenothreshold=lang_node["linenothreshold"], + ) + self.do_parse(self.content, content_node) + + # Restore prior language highlighting, if needed + if lang_node["lang"] != "QMP": + content_node += addnodes.highlightlang(**lang_node.attributes) + return content_node.children def run(self) -> List[nodes.Node]: From patchwork Wed Jul 3 21:01:39 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722785 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 979CCC2BD09 for ; Wed, 3 Jul 2024 21:04:04 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77a-0000or-JG; Wed, 03 Jul 2024 17:02:34 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77Z-0000nI-Fs for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:33 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77Y-0001DU-26 for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:33 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040551; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=PagiVVcxaoz6SG+vMEHIcFhw1tdKzH4mYLKugaIWlWs=; b=P9CyutWBqrM/GjgHpLEtKRsjvFQbA8O4EXpoo14n1o/7UiEexM8O/oGlKSP8dpu7O2+7KP 3YkUCrDtxAQo+KziIoS+VcVr4qWOyQjmYn0XQH33AKZdLPTf3ipY3X76QN2MvB+qN41KF+ 3yDntDshhMzJyiF6ucwytWXuGFbAsHg= Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-7-Cx_fKnGuPXGPL6BUgfI3Gg-1; Wed, 03 Jul 2024 17:02:23 -0400 X-MC-Unique: Cx_fKnGuPXGPL6BUgfI3Gg-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 383D419560B2; Wed, 3 Jul 2024 21:02:21 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B81251955E8F; Wed, 3 Jul 2024 21:02:14 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , Harmonie Snow , John Snow Subject: [PATCH 4/8] docs/sphinx: add CSS styling for qmp-example directive Date: Wed, 3 Jul 2024 17:01:39 -0400 Message-ID: <20240703210144.339530-5-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Harmonie Snow Add CSS styling for qmp-example directives to increase readability and consistently style all example blocks. Signed-off-by: Harmonie Snow Signed-off-by: John Snow Acked-by: Markus Armbruster --- docs/sphinx-static/theme_overrides.css | 49 ++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css index c70ef951286..965ecac54fd 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -87,6 +87,55 @@ div[class^="highlight"] pre { padding-bottom: 1px; } +/* qmp-example directive styling */ + +.rst-content .admonition-example { + /* do not apply the standard admonition background */ + background-color: transparent; + border: solid #ffd2ed 1px; +} + +.rst-content .admonition-example > .admonition-title:before { + content: "▷"; +} + +.rst-content .admonition-example > .admonition-title { + background-color: #5980a6; +} + +.rst-content .admonition-example > div[class^="highlight"] { + /* make code boxes take up the full width of the admonition w/o margin */ + margin-left: -12px; + margin-right: -12px; + + border-top: 1px solid #ffd2ed; + border-bottom: 1px solid #ffd2ed; + border-left: 0px; + border-right: 0px; +} + +.rst-content .admonition-example > div[class^="highlight"]:nth-child(2) { + /* If a code box is the second element in an example admonition, + * it is the first child after the title. let it sit flush against + * the title. */ + margin-top: -12px; + border-top: 0px; +} + +.rst-content .admonition-example > div[class^="highlight"]:last-child { + /* If a code box is the final element in an example admonition, don't + * render margin below it; let it sit flush with the end of the + * admonition box */ + margin-bottom: -12px; + border-bottom: 0px; +} + +.rst-content .admonition-example .highlight { + background-color: #fffafd; +} + +/* end qmp-example styling */ + @media screen { /* content column From patchwork Wed Jul 3 21:01:40 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722779 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 2FD54C3271E for ; Wed, 3 Jul 2024 21:03:19 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77f-0000xg-A4; Wed, 03 Jul 2024 17:02:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77e-0000uh-8H for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:38 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77a-0001No-7n for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:37 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040553; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3tU0d4ey1gw/7IOODQ9HwK7cC5ryedYLQnuP6Uprmm4=; b=BKchpbULlITsgocxqeSx2Uuc0sdKDKXn5p2zVN/fN52MCszs+Qzb4rTGnj+GW9JhHQ2JiT 0Z7I2frpsXSqA4DYHMWjX8R3I+YJoyaiyGZB4yWSmyPFtPoW9IyYrQV2zAzWQePrSYwSlJ 0d9tRTiQVycIpE1urBxAYai8/P/VGPc= Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-507-usFvzLeXMSuXEs8sTSc-dw-1; Wed, 03 Jul 2024 17:02:30 -0400 X-MC-Unique: usFvzLeXMSuXEs8sTSc-dw-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 44905195609E; Wed, 3 Jul 2024 21:02:28 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 6DC371955F21; Wed, 3 Jul 2024 21:02:21 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 5/8] qapi: convert "Example" sections without titles Date: Wed, 3 Jul 2024 17:01:40 -0400 Message-ID: <20240703210144.339530-6-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples. See commit-3: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+3: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- qapi/acpi.json | 4 +-- qapi/block-core.json | 64 +++++++++++++++++++++------------------- qapi/block.json | 18 ++++++----- qapi/char.json | 24 +++++++++------ qapi/control.json | 8 ++--- qapi/dump.json | 8 ++--- qapi/machine-target.json | 2 +- qapi/machine.json | 38 ++++++++++++------------ qapi/migration.json | 58 ++++++++++++++++++------------------ qapi/misc-target.json | 22 +++++++------- qapi/misc.json | 32 ++++++++++---------- qapi/net.json | 20 +++++++------ qapi/pci.json | 2 +- qapi/qdev.json | 10 ++++--- qapi/qom.json | 8 ++--- qapi/replay.json | 8 ++--- qapi/rocker.json | 8 ++--- qapi/run-state.json | 30 +++++++++---------- qapi/tpm.json | 6 ++-- qapi/trace.json | 4 +-- qapi/transaction.json | 2 +- qapi/ui.json | 34 ++++++++++----------- qapi/vfio.json | 2 +- qapi/virtio.json | 2 +- qapi/yank.json | 4 +-- 25 files changed, 216 insertions(+), 202 deletions(-) diff --git a/qapi/acpi.json b/qapi/acpi.json index aa4dbe57943..045dab6228b 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -111,7 +111,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-acpi-ospm-status" } # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, @@ -131,7 +131,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # <- { "event": "ACPI_DEVICE_OST", # "data": { "info": { "device": "d1", "slot": "0", diff --git a/qapi/block-core.json b/qapi/block-core.json index 9ef23ec02ae..4e0f0395146 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -764,7 +764,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-block" } # <- { @@ -1168,7 +1168,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { @@ -1461,7 +1461,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "block_resize", # "arguments": { "device": "scratch", "size": 1073741824 } } @@ -1682,7 +1682,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-snapshot-sync", # "arguments": { "device": "ide-hd0", @@ -1715,7 +1715,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { "driver": "qcow2", @@ -1861,7 +1861,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-commit", # "arguments": { "device": "virtio0", @@ -1899,7 +1899,7 @@ # # Since: 1.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "drive-backup", # "arguments": { "device": "drive0", @@ -1925,7 +1925,7 @@ # # Since: 2.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-backup", # "arguments": { "device": "src-id", @@ -1949,7 +1949,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-named-block-nodes" } # <- { "return": [ { "ro":false, @@ -2130,7 +2130,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "drive-mirror", # "arguments": { "device": "ide-hd0", @@ -2307,7 +2307,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-add", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2331,7 +2331,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-remove", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2354,7 +2354,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-clear", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2375,7 +2375,7 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-enable", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2396,7 +2396,7 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-disable", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2428,7 +2428,7 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-dirty-bitmap-merge", # "arguments": { "node": "drive0", "target": "bitmap0", @@ -2537,7 +2537,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-mirror", # "arguments": { "device": "ide-hd0", @@ -2862,7 +2862,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-stream", # "arguments": { "device": "virtio0", @@ -4801,7 +4801,7 @@ # # Since: 2.9 # -# Examples: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { @@ -4815,6 +4815,8 @@ # } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -4899,7 +4901,7 @@ # # Since: 2.9 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { @@ -5548,7 +5550,7 @@ # .. note:: If action is "stop", a STOP event will eventually follow the # BLOCK_IO_ERROR event. # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "", "node-name": "drive", "fatal": false, @@ -5597,7 +5599,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_IO_ERROR", # "data": { "device": "ide0-hd1", @@ -5637,7 +5639,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_COMPLETED", # "data": { "type": "stream", "device": "virtio-disk0", @@ -5672,7 +5674,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_CANCELLED", # "data": { "type": "stream", "device": "virtio-disk0", @@ -5701,7 +5703,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_ERROR", # "data": { "device": "ide0-hd1", @@ -5736,7 +5738,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_READY", # "data": { "device": "drive0", "type": "mirror", "speed": 0, @@ -5764,7 +5766,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # <- { "event": "BLOCK_JOB_PENDING", # "data": { "type": "mirror", "id": "backup_1" }, @@ -5838,7 +5840,7 @@ # # Since: 2.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "block-set-write-threshold", # "arguments": { "node-name": "mydev", @@ -5989,7 +5991,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # <- { "event": "QUORUM_FAILURE", # "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, @@ -6077,7 +6079,7 @@ # # Since: 1.7 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-snapshot-internal-sync", # "arguments": { "device": "ide-hd0", @@ -6116,7 +6118,7 @@ # # Since: 1.7 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-snapshot-delete-internal-sync", # "arguments": { "device": "ide-hd0", diff --git a/qapi/block.json b/qapi/block.json index ea81d9e1921..c8e52bc2d29 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -117,7 +117,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } # <- { "return": {} } @@ -161,7 +161,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-open-tray", # "arguments": { "id": "ide0-1-0" } } @@ -199,7 +199,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-close-tray", # "arguments": { "id": "ide0-1-0" } } @@ -231,7 +231,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-remove-medium", # "arguments": { "id": "ide0-1-0" } } @@ -272,7 +272,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "blockdev-add", # "arguments": { @@ -397,7 +397,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "DEVICE_TRAY_MOVED", # "data": { "device": "ide1-cd0", @@ -421,7 +421,7 @@ # # Since: 3.0 # -# Example: +# .. qmp-example:: # # <- { "event": "PR_MANAGER_STATUS_CHANGED", # "data": { "id": "pr-helper0", @@ -463,7 +463,7 @@ # # Since: 1.1 # -# Examples: +# .. qmp-example:: # # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "virtio-blk-pci0/virtio-backend", @@ -483,6 +483,8 @@ # "iops_size": 0 } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "ide0-1-0", # "bps": 1000000, diff --git a/qapi/char.json b/qapi/char.json index 5eabf8e7645..5e4aeb9799d 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -40,7 +40,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-chardev" } # <- { @@ -86,7 +86,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-chardev-backends" } # <- { @@ -141,7 +141,7 @@ # # Since: 1.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "ringbuf-write", # "arguments": { "device": "foo", @@ -177,7 +177,7 @@ # # Since: 1.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "ringbuf-read", # "arguments": { "device": "foo", @@ -699,19 +699,23 @@ # # Since: 1.4 # -# Examples: +# .. qmp-example:: # # -> { "execute" : "chardev-add", # "arguments" : { "id" : "foo", # "backend" : { "type" : "null", "data" : {} } } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute" : "chardev-add", # "arguments" : { "id" : "bar", # "backend" : { "type" : "file", # "data" : { "out" : "/tmp/bar.log" } } } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute" : "chardev-add", # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } @@ -735,13 +739,15 @@ # # Since: 2.10 # -# Examples: +# .. qmp-example:: # # -> { "execute" : "chardev-change", # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } # <- { "return": { "pty" : "/dev/pty/42" } } # +# .. qmp-example:: +# # -> {"execute" : "chardev-change", # "arguments" : { # "id" : "charchannel2", @@ -772,7 +778,7 @@ # # Since: 1.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } # <- { "return": {} } @@ -789,7 +795,7 @@ # # Since: 2.10 # -# Example: +# .. qmp-example:: # # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } # <- { "return": {} } @@ -810,7 +816,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # <- { "event": "VSERPORT_CHANGE", # "data": { "id": "channel0", "open": true }, diff --git a/qapi/control.json b/qapi/control.json index fe2af45120b..950443df9d4 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -16,7 +16,7 @@ # the QMP greeting message. If the field is not provided, it # means no QMP capabilities will be enabled. (since 2.12) # -# Example: +# .. qmp-example:: # # -> { "execute": "qmp_capabilities", # "arguments": { "enable": [ "oob" ] } } @@ -97,7 +97,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-version" } # <- { @@ -134,7 +134,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-commands" } # <- { @@ -165,7 +165,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "quit" } # <- { "return": {} } diff --git a/qapi/dump.json b/qapi/dump.json index f9aee7ea1dd..d8145dad979 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -94,7 +94,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "dump-guest-memory", # "arguments": { "paging": false, "protocol": "fd:dump" } } @@ -150,7 +150,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-dump" } # <- { "return": { "status": "active", "completed": 1024000, @@ -171,7 +171,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # <- { "event": "DUMP_COMPLETED", # "data": { "result": { "total": 1090650112, "status": "completed", @@ -202,7 +202,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-dump-guest-memory-capability" } # <- { "return": { "formats": diff --git a/qapi/machine-target.json b/qapi/machine-target.json index a8d9ec87f59..7edb876b5c3 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -475,7 +475,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # <- { "event": "CPU_POLARIZATION_CHANGE", # "data": { "polarization": "horizontal" }, diff --git a/qapi/machine.json b/qapi/machine.json index f15ad1b43e2..83f60b319c7 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -104,7 +104,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-cpus-fast" } # <- { "return": [ @@ -221,7 +221,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-machines", "arguments": { "compat-props": true } } # <- { "return": [ @@ -320,7 +320,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-uuid" } # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } @@ -354,7 +354,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "system_reset" } # <- { "return": {} } @@ -373,7 +373,7 @@ # request or that it has shut down. Many guests will respond to this # command by prompting the user in some way. # -# Example: +# .. qmp-example:: # # -> { "execute": "system_powerdown" } # <- { "return": {} } @@ -393,7 +393,7 @@ # .. note:: Prior to 4.0, this command does nothing in case the guest # isn't suspended. # -# Example: +# .. qmp-example:: # # -> { "execute": "system_wakeup" } # <- { "return": {} } @@ -444,7 +444,7 @@ # .. note:: Prior to 2.1, this command was only supported for x86 and # s390 VMs. # -# Example: +# .. qmp-example:: # # -> { "execute": "inject-nmi" } # <- { "return": {} } @@ -473,7 +473,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } @@ -842,7 +842,7 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. qmp-example:: # # -> { "execute": "memsave", # "arguments": { "val": 10, @@ -868,7 +868,7 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. qmp-example:: # # -> { "execute": "pmemsave", # "arguments": { "val": 10, @@ -929,7 +929,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memdev" } # <- { "return": [ @@ -1166,7 +1166,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-balloon" } # <- { "return": { @@ -1190,7 +1190,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # <- { "event": "BALLOON_CHANGE", # "data": { "actual": 944766976 }, @@ -1232,7 +1232,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-hv-balloon-status-report" } # <- { "return": { @@ -1253,7 +1253,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # <- { "event": "HV_BALLOON_STATUS_REPORT", # "data": { "committed": 816640000, "available": 3333054464 }, @@ -1285,7 +1285,7 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memory-size-summary" } # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } @@ -1564,7 +1564,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memory-devices" } # <- { "return": [ { "data": @@ -1598,7 +1598,7 @@ # # Since: 5.1 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", # "data": { "id": "vm0", "size": 1073741824, @@ -1856,7 +1856,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "dumpdtb" } # "arguments": { "filename": "fdt.dtb" } } diff --git a/qapi/migration.json b/qapi/migration.json index 26ad5e5e7a3..a4391ea7e6f 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -514,7 +514,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-set-capabilities" , "arguments": # { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } @@ -532,7 +532,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-migrate-capabilities" } # <- { "return": [ @@ -1053,7 +1053,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-set-parameters" , # "arguments": { "multifd-channels": 5 } } @@ -1256,7 +1256,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-migrate-parameters" } # <- { "return": { @@ -1280,7 +1280,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-start-postcopy" } # <- { "return": {} } @@ -1296,7 +1296,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, # "event": "MIGRATION", @@ -1315,7 +1315,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, # "event": "MIGRATION_PASS", "data": {"pass": 2} } @@ -1399,7 +1399,7 @@ # # Since: 3.1 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, # "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } @@ -1442,7 +1442,7 @@ # # Since: 2.8 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-colo-lost-heartbeat" } # <- { "return": {} } @@ -1461,7 +1461,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate_cancel" } # <- { "return": {} } @@ -1477,7 +1477,7 @@ # # Since: 2.11 # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-continue" , "arguments": # { "state": "pre-switchover" } } @@ -1610,7 +1610,7 @@ # 6. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } # <- { "return": {} } @@ -1689,7 +1689,7 @@ # 5. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-incoming", # "arguments": { "uri": "tcp:0:4446" } } @@ -1740,7 +1740,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-save-devices-state", # "arguments": { "filename": "/tmp/save" } } @@ -1758,7 +1758,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-set-global-dirty-log", # "arguments": { "enable": true } } @@ -1778,7 +1778,7 @@ # # Since: 2.7 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-load-devices-state", # "arguments": { "filename": "/tmp/resume" } } @@ -1798,7 +1798,7 @@ # @failover: true to do failover, false to stop. Cannot be specified # if 'enable' is true. Default value is false. # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-set-replication", # "arguments": {"enable": true, "primary": false} } @@ -1833,7 +1833,7 @@ # # Returns: A @ReplicationStatus object showing the status. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-xen-replication-status" } # <- { "return": { "error": false } } @@ -1849,7 +1849,7 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" } # <- { "return": {} } @@ -1887,7 +1887,7 @@ # # Returns: A @COLOStatus object showing the status. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-colo-status" } # <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } @@ -1905,7 +1905,7 @@ # # @uri: the URI to be used for the recovery of migration stream. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-recover", # "arguments": { "uri": "tcp:192.168.1.200:12345" } } @@ -1922,7 +1922,7 @@ # # Pause a migration. Currently it only supports postcopy. # -# Example: +# .. qmp-example:: # # -> { "execute": "migrate-pause" } # <- { "return": {} } @@ -1943,7 +1943,7 @@ # # Since: 4.2 # -# Example: +# .. qmp-example:: # # <- { "event": "UNPLUG_PRIMARY", # "data": { "device-id": "hostdev0" }, @@ -2182,7 +2182,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> {"execute": "set-vcpu-dirty-limit"} # "arguments": { "dirty-rate": 200, @@ -2206,7 +2206,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> {"execute": "cancel-vcpu-dirty-limit"}, # "arguments": { "cpu-index": 1 } } @@ -2223,7 +2223,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> {"execute": "query-vcpu-dirty-limit"} # <- {"return": [ @@ -2287,7 +2287,7 @@ # # If @tag already exists, an error will be reported # -# Example: +# .. qmp-example:: # # -> { "execute": "snapshot-save", # "arguments": { @@ -2357,7 +2357,7 @@ # device nodes that can have changed since the original @snapshot-save # command execution. # -# Example: +# .. qmp-example:: # # -> { "execute": "snapshot-load", # "arguments": { @@ -2418,7 +2418,7 @@ # to determine completion and to fetch details of any errors that # arise. # -# Example: +# .. qmp-example:: # # -> { "execute": "snapshot-delete", # "arguments": { diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 2d7d4d89bd5..8d70bd24d8c 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -11,7 +11,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "rtc-reset-reinjection" } # <- { "return": {} } @@ -133,7 +133,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sev" } # <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, @@ -164,7 +164,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sev-launch-measure" } # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } @@ -209,7 +209,7 @@ # # Since: 2.12 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sev-capabilities" } # <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", @@ -263,7 +263,7 @@ # # Since: 6.1 # -# Example: +# .. qmp-example:: # # -> { "execute" : "query-sev-attestation-report", # "arguments": { "mnonce": "aaaaaaa" } } @@ -283,7 +283,7 @@ # # Since: 2.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "dump-skeys", # "arguments": { "filename": "/tmp/skeys" } } @@ -328,7 +328,7 @@ # # Since: 2.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-gic-capabilities" } # <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, @@ -386,7 +386,7 @@ # # Since: 6.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sgx" } # <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, @@ -405,7 +405,7 @@ # # Since: 6.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-sgx-capabilities" } # <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, @@ -480,7 +480,7 @@ # # Since: 8.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-event-list" } # <- { "return": [ @@ -518,7 +518,7 @@ # # Since: 8.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } # <- { "return": { } } diff --git a/qapi/misc.json b/qapi/misc.json index b04efbadec6..4a6f3baeaed 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -30,7 +30,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "add_client", "arguments": { "protocol": "vnc", # "fdname": "myclient" } } @@ -60,7 +60,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-name" } # <- { "return": { "name": "qemu-name" } } @@ -111,7 +111,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-iothreads" } # <- { "return": [ @@ -144,7 +144,7 @@ # In the "suspended" state, it will completely stop the VM and cause # a transition to the "paused" state. (Since 9.0) # -# Example: +# .. qmp-example:: # # -> { "execute": "stop" } # <- { "return": {} } @@ -168,7 +168,7 @@ # this command will transition back to the "suspended" state. (Since # 9.0) # -# Example: +# .. qmp-example:: # # -> { "execute": "cont" } # <- { "return": {} } @@ -192,7 +192,7 @@ # # Since: 3.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-exit-preconfig" } # <- { "return": {} } @@ -232,7 +232,7 @@ # # * Commands that prompt the user for data don't currently work. # -# Example: +# .. qmp-example:: # # -> { "execute": "human-monitor-command", # "arguments": { "command-line": "info kvm" } } @@ -258,7 +258,7 @@ # The 'closefd' command can be used to explicitly close the file # descriptor when it is no longer needed. # -# Example: +# .. qmp-example:: # # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } @@ -285,7 +285,7 @@ # The 'closefd' command can be used to explicitly close the file # descriptor when it is no longer needed. # -# Example: +# .. qmp-example:: # # -> { "execute": "get-win32-socket", # "arguments": { "info": "abcd123..", "fdname": "skclient" } } @@ -302,7 +302,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } @@ -345,7 +345,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } # <- { "return": { "fdset-id": 1, "fd": 3 } } @@ -374,7 +374,7 @@ # .. note:: If @fd is not specified, all file descriptors in @fdset-id # will be removed. # -# Example: +# .. qmp-example:: # # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } # <- { "return": {} } @@ -420,7 +420,7 @@ # # .. note:: The list of fd sets is shared by all monitor connections. # -# Example: +# .. qmp-example:: # # -> { "execute": "query-fdsets" } # <- { "return": [ @@ -523,7 +523,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-command-line-options", # "arguments": { "option": "option-rom" } } @@ -565,7 +565,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "RTC_CHANGE", # "data": { "offset": 78 }, @@ -592,7 +592,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # <- { "event": "VFU_CLIENT_HANGUP", # "data": { "vfu-id": "vfu1", diff --git a/qapi/net.json b/qapi/net.json index dd6c365c34d..9a723e56b50 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -26,7 +26,7 @@ # command will succeed even if the network adapter does not support # link status notification. # -# Example: +# .. qmp-example:: # # -> { "execute": "set_link", # "arguments": { "name": "e1000.0", "up": false } } @@ -46,7 +46,7 @@ # Errors: # - If @type is not a valid network backend, DeviceNotFound # -# Example: +# .. qmp-example:: # # -> { "execute": "netdev_add", # "arguments": { "type": "user", "id": "netdev1", @@ -68,7 +68,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } # <- { "return": {} } @@ -836,7 +836,7 @@ # # Since: 1.6 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } # <- { "return": [ @@ -881,7 +881,7 @@ # # Since: 1.6 # -# Example: +# .. qmp-example:: # # <- { "event": "NIC_RX_FILTER_CHANGED", # "data": { "name": "vnet0", @@ -930,7 +930,7 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# Example: +# .. qmp-example:: # # -> { "execute": "announce-self", # "arguments": { @@ -955,7 +955,7 @@ # # Since: 4.2 # -# Example: +# .. qmp-example:: # # <- { "event": "FAILOVER_NEGOTIATED", # "data": { "device-id": "net1" }, @@ -975,7 +975,7 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", @@ -983,6 +983,8 @@ # "host": "::1", "type": "inet" } }, # "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # +# .. qmp-example:: +# # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } }, @@ -1001,7 +1003,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # <- { "event": "NETDEV_STREAM_DISCONNECTED", # "data": {"netdev-id": "netdev0"}, diff --git a/qapi/pci.json b/qapi/pci.json index 8287d15dd0b..8e2ca560ee1 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -182,7 +182,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-pci" } # <- { "return": [ diff --git a/qapi/qdev.json b/qapi/qdev.json index d031fc3590d..e91ca0309df 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -62,7 +62,7 @@ # the ``-device DEVICE,help`` command-line argument, where DEVICE # is the device's name. # -# Example: +# .. qmp-example:: # # -> { "execute": "device_add", # "arguments": { "driver": "e1000", "id": "net1", @@ -104,12 +104,14 @@ # # Since: 0.14 # -# Examples: +# .. qmp-example:: # # -> { "execute": "device_del", # "arguments": { "id": "net1" } } # <- { "return": {} } # +# .. qmp-example:: +# # -> { "execute": "device_del", # "arguments": { "id": "/machine/peripheral-anon/device[0]" } } # <- { "return": {} } @@ -130,7 +132,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # <- { "event": "DEVICE_DELETED", # "data": { "device": "virtio-net-pci-0", @@ -152,7 +154,7 @@ # # Since: 6.2 # -# Example: +# .. qmp-example:: # # <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", # "data": { "device": "core1", diff --git a/qapi/qom.json b/qapi/qom.json index f582a1357b7..fb365e5ce6b 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -59,7 +59,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "qom-list", # "arguments": { "path": "/chardevs" } } @@ -139,7 +139,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "qom-set", # "arguments": { "path": "/machine", @@ -1154,7 +1154,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "object-add", # "arguments": { "qom-type": "rng-random", "id": "rng1", @@ -1176,7 +1176,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "object-del", "arguments": { "id": "rng1" } } # <- { "return": {} } diff --git a/qapi/replay.json b/qapi/replay.json index d3559f9c8f7..35e0c4a6926 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -54,7 +54,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-replay" } # <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } @@ -76,7 +76,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } # <- { "return": {} } @@ -91,7 +91,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "replay-delete-break" } # <- { "return": {} } @@ -112,7 +112,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } # <- { "return": {} } diff --git a/qapi/rocker.json b/qapi/rocker.json index 9f95e638309..2e63dcb3d6f 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -30,7 +30,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } # <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} @@ -98,7 +98,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } # <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", @@ -240,7 +240,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker-of-dpa-flows", # "arguments": { "name": "sw1" } } @@ -315,7 +315,7 @@ # # Since: 2.4 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-rocker-of-dpa-groups", # "arguments": { "name": "sw1" } } diff --git a/qapi/run-state.json b/qapi/run-state.json index 252d7d6afa7..718a3c958e9 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -123,7 +123,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-status" } # <- { "return": { "running": true, @@ -152,7 +152,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "SHUTDOWN", # "data": { "guest": true, "reason": "guest-shutdown" }, @@ -168,7 +168,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "POWERDOWN", # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } @@ -189,7 +189,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "RESET", # "data": { "guest": false, "reason": "guest-reset" }, @@ -204,7 +204,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "STOP", # "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } @@ -218,7 +218,7 @@ # # Since: 0.12 # -# Example: +# .. qmp-example:: # # <- { "event": "RESUME", # "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } @@ -233,7 +233,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "SUSPEND", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } @@ -252,7 +252,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # <- { "event": "SUSPEND_DISK", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } @@ -267,7 +267,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # <- { "event": "WAKEUP", # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } @@ -289,7 +289,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "WATCHDOG", # "data": { "action": "reset" }, @@ -382,7 +382,7 @@ # # Since: 2.11 # -# Example: +# .. qmp-example:: # # -> { "execute": "watchdog-set-action", # "arguments": { "action": "inject-nmi" } } @@ -406,7 +406,7 @@ # # Since: 6.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "set-action", # "arguments": { "reboot": "shutdown", @@ -433,7 +433,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_PANICKED", # "data": { "action": "pause" }, @@ -453,7 +453,7 @@ # # Since: 5.0 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" }, @@ -597,7 +597,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor", diff --git a/qapi/tpm.json b/qapi/tpm.json index 1577b5c259d..a16a72edb98 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -31,7 +31,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-tpm-models" } # <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } @@ -62,7 +62,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-tpm-types" } # <- { "return": [ "passthrough", "emulator" ] } @@ -168,7 +168,7 @@ # # Since: 1.5 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-tpm" } # <- { "return": diff --git a/qapi/trace.json b/qapi/trace.json index 9ebb6d9eaf5..eb5f63f5135 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -51,7 +51,7 @@ # # Since: 2.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "trace-event-get-state", # "arguments": { "name": "qemu_memalign" } } @@ -74,7 +74,7 @@ # # Since: 2.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "trace-event-set-state", # "arguments": { "name": "qemu_memalign", "enable": true } } diff --git a/qapi/transaction.json b/qapi/transaction.json index bcb05fdedd6..b0ae3437eba 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -244,7 +244,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "transaction", # "arguments": { "actions": [ diff --git a/qapi/ui.json b/qapi/ui.json index 5bcccbfc930..c0e94fd0ed0 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -83,7 +83,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "set_password", "arguments": { "protocol": "vnc", # "password": "secret" } } @@ -144,7 +144,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "expire_password", "arguments": { "protocol": "vnc", # "time": "+60" } } @@ -186,7 +186,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "screendump", # "arguments": { "filename": "/tmp/image" } } @@ -330,7 +330,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-spice" } # <- { "return": { @@ -379,7 +379,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_CONNECTED", @@ -405,7 +405,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_INITIALIZED", @@ -432,7 +432,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_DISCONNECTED", @@ -453,7 +453,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_MIGRATE_COMPLETED" } @@ -661,7 +661,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-vnc" } # <- { "return": { @@ -726,7 +726,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_CONNECTED", # "data": { @@ -753,7 +753,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_INITIALIZED", # "data": { @@ -779,7 +779,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_DISCONNECTED", # "data": { @@ -827,7 +827,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-mice" } # <- { "return": [ @@ -1036,7 +1036,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "send-key", # "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, @@ -1615,7 +1615,7 @@ # # Since: 6.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "display-reload", # "arguments": { "type": "vnc", "tls-certs": true } } @@ -1672,7 +1672,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "display-update", # "arguments": { "type": "vnc", "addresses": @@ -1703,7 +1703,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "client_migrate_info", # "arguments": { "protocol": "spice", diff --git a/qapi/vfio.json b/qapi/vfio.json index a0e5013188a..40cbcde02eb 100644 --- a/qapi/vfio.json +++ b/qapi/vfio.json @@ -50,7 +50,7 @@ # # Since: 9.1 # -# Example: +# .. qmp-example:: # # <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 }, # "event": "VFIO_MIGRATION", diff --git a/qapi/virtio.json b/qapi/virtio.json index b91f3cdd0df..f4323cc35e8 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -34,7 +34,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-query-virtio" } # <- { "return": [ diff --git a/qapi/yank.json b/qapi/yank.json index 89f2f4d199b..30f46c97c98 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -81,7 +81,7 @@ # Errors: # - If any of the YankInstances doesn't exist, DeviceNotFound # -# Example: +# .. qmp-example:: # # -> { "execute": "yank", # "arguments": { @@ -104,7 +104,7 @@ # # Returns: list of @YankInstance # -# Example: +# .. qmp-example:: # # -> { "execute": "query-yank" } # <- { "return": [ From patchwork Wed Jul 3 21:01:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722783 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id C4D23C2BD09 for ; Wed, 3 Jul 2024 21:03:52 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77o-0001Ce-LH; Wed, 03 Jul 2024 17:02:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77n-00017y-E0 for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77l-0001dP-7y for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:47 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040562; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=EZKq8NdPRtFQaqOS66UrV4r6O8zGuQk00MpGkJ/TuUc=; b=U/mnmr5djBx1+Ycgwl9aIcMMPRx47wiqwCVW0G2E8dU/dX4Wq04inpoTItJRWgG4u25xdp BZpzAZp1USya9T/dzh2ik/EotrVi9ZQRm/gpgb5fITLcpU0fe0aUrNTUppyRkvowa0pozX jsy+zhOWBxyfD9m8QQ7TGDOd/gCvqlk= Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-217-RMW5qZbVNqmJXkIyr10UZA-1; Wed, 03 Jul 2024 17:02:38 -0400 X-MC-Unique: RMW5qZbVNqmJXkIyr10UZA-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A7BAF1955F56; Wed, 3 Jul 2024 21:02:36 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 8D41E1955F21; Wed, 3 Jul 2024 21:02:28 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 6/8] qapi: convert "Example" sections with titles Date: Wed, 3 Jul 2024 17:01:41 -0400 Message-ID: <20240703210144.339530-7-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org When an Example section has a brief explanation, convert it to a qmp-example:: section using the :title: option. Rule of thumb: If the title can fit on a single line and requires no rST markup, it's a good candidate for using the :title: option of qmp-example. In this patch, trailing punctuation is removed from the title section for consistent headline aesthetics. In just one case, specifics of the example are removed to make the title read better. See commit-4: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+2: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- qapi/block-core.json | 24 ++++++++++++------------ qapi/block.json | 13 ++++++------- qapi/migration.json | 25 ++++++++++++++----------- qapi/qom.json | 8 ++++---- qapi/ui.json | 11 ++++++----- qapi/virtio.json | 19 ++++++++++--------- 6 files changed, 52 insertions(+), 48 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 4e0f0395146..a371e3464d2 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -5885,9 +5885,8 @@ # # Since: 2.7 # -# Examples: -# -# 1. Add a new node to a quorum +# .. qmp-example:: +# :title: Add a new node to a quorum # # -> { "execute": "blockdev-add", # "arguments": { @@ -5901,7 +5900,8 @@ # "node": "new_node" } } # <- { "return": {} } # -# 2. Delete a quorum's node +# .. qmp-example:: +# :title: Delete a quorum's node # # -> { "execute": "x-blockdev-change", # "arguments": { "parent": "disk1", @@ -5937,16 +5937,16 @@ # # Since: 2.12 # -# Examples: -# -# 1. Move a node into an IOThread +# .. qmp-example:: +# :title: Move a node into an IOThread # # -> { "execute": "x-blockdev-set-iothread", # "arguments": { "node-name": "disk1", # "iothread": "iothread0" } } # <- { "return": {} } # -# 2. Move a node into the main loop +# .. qmp-example:: +# :title: Move a node into the main loop # # -> { "execute": "x-blockdev-set-iothread", # "arguments": { "node-name": "disk1", @@ -6022,16 +6022,16 @@ # # Since: 2.0 # -# Examples: -# -# 1. Read operation +# .. qmp-example:: +# :title: Read operation # # <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, # "type": "read" }, # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # -# 2. Flush operation +# .. qmp-example:: +# :title: Flush operation # # <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, diff --git a/qapi/block.json b/qapi/block.json index c8e52bc2d29..5ddd061e964 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -342,9 +342,8 @@ # # Since: 2.5 # -# Examples: -# -# 1. Change a removable medium +# .. qmp-example:: +# :title: Change a removable medium # # -> { "execute": "blockdev-change-medium", # "arguments": { "id": "ide0-1-0", @@ -352,7 +351,8 @@ # "format": "raw" } } # <- { "return": {} } # -# 2. Load a read-only medium into a writable drive +# .. qmp-example:: +# :title: Load a read-only medium into a writable drive # # -> { "execute": "blockdev-change-medium", # "arguments": { "id": "floppyA", @@ -577,9 +577,8 @@ # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # -# Example: -# -# Remove all latency histograms: +# .. qmp-example:: +# :title: Remove all latency histograms # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } diff --git a/qapi/migration.json b/qapi/migration.json index a4391ea7e6f..37ce8afa380 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -287,14 +287,14 @@ # # Since: 0.14 # -# Examples: -# -# 1. Before the first migration +# .. qmp-example:: +# :title: Before the first migration # # -> { "execute": "query-migrate" } # <- { "return": {} } # -# 2. Migration is done and has succeeded +# .. qmp-example:: +# :title: Migration is done and has succeeded # # -> { "execute": "query-migrate" } # <- { "return": { @@ -314,12 +314,14 @@ # } # } # -# 3. Migration is done and has failed +# .. qmp-example:: +# :title: Migration is done and has failed # # -> { "execute": "query-migrate" } # <- { "return": { "status": "failed" } } # -# 4. Migration is being performed: +# .. qmp-example:: +# :title: Migration is being performed # # -> { "execute": "query-migrate" } # <- { @@ -340,7 +342,8 @@ # } # } # -# 5. Migration is being performed and XBZRLE is active: +# .. qmp-example:: +# :title: Migration is being performed and XBZRLE is active # # -> { "execute": "query-migrate" } # <- { @@ -2131,15 +2134,15 @@ # # Since: 5.2 # -# Examples: -# -# 1. Measurement is in progress: +# .. qmp-example:: +# :title: Measurement is in progress # # <- {"status": "measuring", "sample-pages": 512, # "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, # "calc-time-unit": "second"} # -# 2. Measurement has been completed: +# .. qmp-example:: +# :title: Measurement has been completed # # <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, # "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, diff --git a/qapi/qom.json b/qapi/qom.json index fb365e5ce6b..1b3e6c94b73 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -104,16 +104,16 @@ # # Since: 1.2 # -# Examples: -# -# 1. Use absolute path +# .. qmp-example:: +# :title: Use absolute path # # -> { "execute": "qom-get", # "arguments": { "path": "/machine/unattached/device[0]", # "property": "hotplugged" } } # <- { "return": false } # -# 2. Use partial path +# .. qmp-example:: +# :title: Use partial path # # -> { "execute": "qom-get", # "arguments": { "path": "unattached/sysbus", diff --git a/qapi/ui.json b/qapi/ui.json index c0e94fd0ed0..779b472f064 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1272,9 +1272,8 @@ # property, so it is possible to map which console belongs to which # device and display. # -# Examples: -# -# 1. Press left mouse button. +# .. qmp-example:: +# :title: Press left mouse button # # -> { "execute": "input-send-event", # "arguments": { "device": "video0", @@ -1288,7 +1287,8 @@ # "data" : { "down": false, "button": "left" } } ] } } # <- { "return": {} } # -# 2. Press ctrl-alt-del. +# .. qmp-example:: +# :title: Press ctrl-alt-del # # -> { "execute": "input-send-event", # "arguments": { "events": [ @@ -1300,7 +1300,8 @@ # "key": {"type": "qcode", "data": "delete" } } } ] } } # <- { "return": {} } # -# 3. Move mouse pointer to absolute coordinates (20000, 400). +# .. qmp-example:: +# :title: Move mouse pointer to absolute coordinates # # -> { "execute": "input-send-event" , # "arguments": { "events": [ diff --git a/qapi/virtio.json b/qapi/virtio.json index f4323cc35e8..d965c98ad2b 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -690,9 +690,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Get vhost_virtqueue status for vhost-crypto +# .. qmp-example:: +# :title: Get vhost_virtqueue status for vhost-crypto # # -> { "execute": "x-query-virtio-vhost-queue-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", @@ -715,7 +714,8 @@ # } # } # -# 2. Get vhost_virtqueue status for vhost-vsock +# .. qmp-example:: +# :title: Get vhost_virtqueue status for vhost-vsock # # -> { "execute": "x-query-virtio-vhost-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", @@ -839,9 +839,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Introspect on virtio-net's VirtQueue 0 at index 5 +# .. qmp-example:: +# :title: Introspect on virtio-net's VirtQueue 0 at index 5 # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend", @@ -870,7 +869,8 @@ # } # } # -# 2. Introspect on virtio-crypto's VirtQueue 1 at head +# .. qmp-example:: +# :title: Introspect on virtio-crypto's VirtQueue 1 at head # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", @@ -898,7 +898,8 @@ # } # } # -# 3. Introspect on virtio-scsi's VirtQueue 2 at head +# .. qmp-example:: +# :title: Introspect on virtio-scsi's VirtQueue 2 at head # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend", From patchwork Wed Jul 3 21:01:42 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722782 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 9CA2EC31D97 for ; Wed, 3 Jul 2024 21:03:51 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP77u-0001JC-CQ; Wed, 03 Jul 2024 17:02:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77t-0001Gt-43 for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:53 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77r-0001i3-9T for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:02:52 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040570; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qEdS/Gb8GO1qphubxtf0mIutzvbw2WgtC4FPzFeseyw=; b=avwIO6tkf5BVxbgCylgIecSB/zWgJtboRhwob+LzIudQFFtfVO2AuDj/r4CaGm8SUbn3BH 7iFeoEx8DolzJO0xbrL74F1LB1e06R8UPcQgp85bpf1EhOh2PfjzUO19ckl49DOye2b4Dv zbY3TXFNlxlx0UfoHc0A/VnNHZtoq7U= Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-445-lcuuY3M9OiyBiXlq1zgWdA-1; Wed, 03 Jul 2024 17:02:46 -0400 X-MC-Unique: lcuuY3M9OiyBiXlq1zgWdA-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 03CA01955BD2; Wed, 3 Jul 2024 21:02:44 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 22F801955E93; Wed, 3 Jul 2024 21:02:36 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 7/8] qapi: convert "Example" sections with longer prose Date: Wed, 3 Jul 2024 17:01:42 -0400 Message-ID: <20240703210144.339530-8-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org These examples require longer explanations or have explanations that require markup to look reasonable when rendered and so use the longer form of the ".. qmp-example::" directive. By using the :annotated: option, the content in the example block is assumed *not* to be a code block literal and is instead parsed as normal rST - with the exception that any code literal blocks after `::` will assumed to be a QMP code literal block. Note: There's one title-less conversion in this patch that comes along for the ride because it's part of a larger "Examples" block that was better to convert all at once. See commit-5: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+1: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- qapi/block.json | 26 ++++++++++++++++---------- qapi/machine.json | 30 ++++++++++++++++++++---------- qapi/migration.json | 7 +++++-- qapi/virtio.json | 24 ++++++++++++++++++------ 4 files changed, 59 insertions(+), 28 deletions(-) diff --git a/qapi/block.json b/qapi/block.json index 5ddd061e964..d95e9fd8140 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -545,31 +545,37 @@ # # Since: 4.0 # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histograms for all io types with intervals -# [0, 10), [10, 50), [50, 100), [100, +inf): +# Set new histograms for all io types with intervals +# [0, 10), [10, 50), [50, 100), [100, +inf):: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries": [10, 50, 100] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histogram only for write, other histograms will remain -# not changed (or not created): +# Set new histogram only for write, other histograms will remain +# not changed (or not created):: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries-write": [10, 50, 100] } } # <- { "return": {} } # -# Example: +# .. qmp-example:: +# :annotated: # -# Set new histograms with the following intervals: -# read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) -# write: [0, 1000), [1000, 5000), [5000, +inf) +# Set new histograms with the following intervals: +# +# - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) +# - write: [0, 1000), [1000, 5000), [5000, +inf) +# +# :: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", diff --git a/qapi/machine.json b/qapi/machine.json index 83f60b319c7..0a5ffe652b7 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1047,10 +1047,11 @@ # # Since: 2.7 # -# Examples: +# .. qmp-example:: +# :annotated: # -# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -# -cpu POWER8: +# For pseries machine type started with +# ``-smp 2,cores=2,maxcpus=4 -cpu POWER8``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1060,7 +1061,10 @@ # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} # ]} # -# For pc machine type started with -smp 1,maxcpus=2: +# .. qmp-example:: +# :annotated: +# +# For pc machine type started with ``-smp 1,maxcpus=2``:: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1075,8 +1079,11 @@ # } # ]} # -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -# -cpu qemu (Since: 2.11): +# .. qmp-example:: +# :annotated: +# +# For s390x-virtio-ccw machine type started with +# ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11):: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1130,12 +1137,15 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: +# :annotated: # -# -> { "execute": "balloon", "arguments": { "value": 536870912 } } -# <- { "return": {} } +# :: # -# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# -> { "execute": "balloon", "arguments": { "value": 536870912 } } +# <- { "return": {} } +# +# With a 2.5GiB guest this command inflated the ballon to 3GiB. ## { 'command': 'balloon', 'data': {'value': 'int'} } diff --git a/qapi/migration.json b/qapi/migration.json index 37ce8afa380..e208a86258a 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -2106,13 +2106,16 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, # "sample-pages": 512} } # <- { "return": {} } # -# Measure dirty rate using dirty bitmap for 500 milliseconds: +# .. qmp-example:: +# :annotated: +# +# Measure dirty rate using dirty bitmap for 500 milliseconds:: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, # "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } diff --git a/qapi/virtio.json b/qapi/virtio.json index d965c98ad2b..26df8b3064b 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -203,9 +203,11 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: +# :annotated: # -# 1. Poll for the status of virtio-crypto (no vhost-crypto active) +# Poll for the status of virtio-crypto (no vhost-crypto active) +# :: # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" } @@ -261,7 +263,11 @@ # } # } # -# 2. Poll for the status of virtio-net (vhost-net is active) +# .. qmp-example:: +# :annotated: +# +# Poll for the status of virtio-net (vhost-net is active) +# :: # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" } @@ -568,9 +574,11 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: +# :annotated: # -# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# :: # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", @@ -593,7 +601,11 @@ # } # } # -# 2. Get VirtQueueStatus for virtio-serial (no vhost) +# .. qmp-example:: +# :annotated: +# +# Get VirtQueueStatus for virtio-serial (no vhost) +# :: # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend", From patchwork Wed Jul 3 21:01:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13722784 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id F2CB3C3271E for ; Wed, 3 Jul 2024 21:03:52 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sP783-0001OJ-GP; Wed, 03 Jul 2024 17:03:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP780-0001Ms-LB for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:03:00 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sP77y-0002J4-Ks for qemu-devel@nongnu.org; Wed, 03 Jul 2024 17:03:00 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1720040577; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=bYt+M1Vz4HSKtH7x62vDhOJdfNxWp/An1HxtiZGPiB4=; b=S3Nz3ra9FjCjtiCITX1/xJndTkz7drek+PVuM1qAN5OxFg5ZlXd6dopzdKQTDoaGwTXR6J 4q9jEM0OPJiJjXvuIBbM18yVaz/4y4Fae7T8WvtXDhb8BUJ9Z5nprNC+fkS1OIu/i3YewK KvirL2Lu6SIMMQuY9oOLmphOMD/ZSJg= Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-214-vxZO8It8OdGnSOBhuJKHjg-1; Wed, 03 Jul 2024 17:02:54 -0400 X-MC-Unique: vxZO8It8OdGnSOBhuJKHjg-1 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 833751954B0C; Wed, 3 Jul 2024 21:02:51 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.34.31]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 21D301955F21; Wed, 3 Jul 2024 21:02:43 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: "Michael S. Tsirkin" , Peter Xu , qemu-block@nongnu.org, =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Kevin Wolf , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Peter Maydell , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Eduardo Habkost , Stefan Berger , =?utf-8?q?Daniel_P=2E_Berrang?= =?utf-8?q?=C3=A9?= , Paolo Bonzini , Fabiano Rosas , Markus Armbruster , Pavel Dovgalyuk , Stefan Hajnoczi , Jason Wang , Lukas Straub , Ani Sinha , Igor Mammedov , Michael Roth , Hanna Reitz , Mads Ynddal , Alex Williamson , Eric Blake , Marcel Apfelbaum , Yanan Wang , Jiri Pirko , John Snow Subject: [PATCH 8/8] qapi: remove "Example" doc section Date: Wed, 3 Jul 2024 17:01:43 -0400 Message-ID: <20240703210144.339530-9-jsnow@redhat.com> In-Reply-To: <20240703210144.339530-1-jsnow@redhat.com> References: <20240703210144.339530-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Fully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match. Migrating to the new syntax --------------------------- The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block. ('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.) Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired. Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive. Why? ---- This patch has several benefits: 1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired. 2. Example sections can now use fully arbitrary rST. 3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets. (To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.) 4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator. (i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.) NOTE: As with the "Notes" conversion patch, this patch (and those preceding) may change the rendering order for Examples in the current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 58 ++++++++++++++++++++++++++++----- scripts/qapi/parser.py | 10 +++++- tests/qapi-schema/doc-good.json | 19 +++++++---- tests/qapi-schema/doc-good.out | 26 ++++++++++----- tests/qapi-schema/doc-good.txt | 23 ++++++------- 5 files changed, 98 insertions(+), 38 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ae97b335cbf..2e10a3cbd69 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ Documentation comments can use most rST markup. In particular, -a ``::`` literal block can be used for examples:: +a ``::`` literal block can be used for pre-formatted text:: # :: # @@ -995,8 +995,8 @@ line "Features:", like this:: # @feature: Description text A tagged section begins with a paragraph that starts with one of the -following words: "Since:", "Example:"/"Examples:", "Returns:", -"Errors:", "TODO:". It ends with the start of a new section. +following words: "Since:", "Returns:", "Errors:", "TODO:". It ends with +the start of a new section. The second and subsequent lines of tagged sections must be indented like this:: @@ -1020,13 +1020,53 @@ detailing a relevant error condition. For example:: A "Since: x.y.z" tagged section lists the release that introduced the definition. -An "Example" or "Examples" section is rendered entirely -as literal fixed-width text. "TODO" sections are not rendered at all -(they are for developers, not users of QMP). In other sections, the -text is formatted, and rST markup can be used. +"TODO" sections are not rendered at all (they are for developers, not +users of QMP). In other sections, the text is formatted, and rST markup +can be used. + +QMP Examples can be added by using the ``.. qmp-example::`` +directive. In its simplest form, this can be used to contain a single +QMP code block which accepts standard JSON syntax with additional server +directionality indicators (``->`` and ``<-``), and elisions (``...``). + +Optionally, a plaintext title may be provided by using the ``:title:`` +directive option. If the title is omitted, the example title will +default to "Example:". + +A simple QMP example:: + + # .. qmp-example:: + # :title: Using query-block + # + # -> { "execute": "query-block" } + # <- { ... } + +More complex or multi-step examples where exposition is needed before or +between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocks must be +entered explicitly with rST's ``::`` syntax. + +Highlighting in non-QMP languages can be accomplished by using the +``.. code-block:: lang`` directive, and non-highlighted text can be +achieved by omitting the language argument. For example:: + # .. qmp-example:: + # :annotated: + # :title: A more complex demonstration + # + # This is a more complex example that can use + # ``arbitrary rST syntax`` in its exposition:: + # + # -> { "execute": "query-block" } + # <- { ... } + # + # Above, lengthy output has been omitted for brevity. + + +Examples of complete definition documentation:: + ## # @BlockStats: # @@ -1058,11 +1098,11 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # } ## { 'command': 'query-blockstats', diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 6ad5663e545..adc85b5b394 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -553,7 +553,7 @@ def get_doc(self) -> 'QAPIDoc': # Note: "sections" with two colons are left alone as # rST markup and not interpreted as a section heading. - # TODO: Remove this error sometime in 2025 or so + # TODO: Remove these errors sometime in 2025 or so # after we've fully transitioned to the new qapidoc # generator. @@ -567,6 +567,14 @@ def get_doc(self) -> 'QAPIDoc': ) raise QAPIParseError(self, emsg) + if 'Example' in match.group(1): + emsg = ( + f"The '{match.group(1)}' section is no longer " + "supported. Please use the '.. qmp-example::' " + "directive, or other suitable markup instead." + ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info, match.group(1)) text = line[match.end():] if text: diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 107123f8a8d..c71d65cd51f 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -172,12 +172,17 @@ # # Duis aute irure dolor # -# Example: +# .. qmp-example:: +# :title: Ideal fast-food burger situation # -# -> in -# <- out +# -> "in" +# <- "out" # -# Examples: +# Examples:: +# +# - Not a QMP code block +# - Merely a preformatted code block literal +# It isn't even an rST list. # - *verbatim* # - {braces} # @@ -199,11 +204,11 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Example: +# .. qmp-example:: # -# -> in +# -> "this example" # -# <- out +# <- "has no title" ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index bd876b6542d..eee18cd436a 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -184,13 +184,21 @@ frobnicate - Ut enim ad minim veniam Duis aute irure dolor - section=Example - -> in - <- out - section=Examples + +.. qmp-example:: + :title: Ideal fast-food burger situation + + -> "in" + <- "out" + +Examples:: + + - Not a QMP code block + - Merely a preformatted code block literal + It isn't even an rST list. - *verbatim* - {braces} - section=None + Note:: Ceci n'est pas une note section=Since @@ -202,10 +210,12 @@ If you're bored enough to read this, go see a video of boxed cats a feature feature=cmd-feat2 another feature - section=Example - -> in + section=None +.. qmp-example:: - <- out + -> "this example" + + <- "has no title" doc symbol=EVT_BOXED body= diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 30d457e5488..cb37db606a6 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -217,17 +217,16 @@ Notes: Duis aute irure dolor +Example: Ideal fast-food burger situation: -Example -~~~~~~~ + -> "in" + <- "out" - -> in - <- out - - -Examples -~~~~~~~~ +Examples: + - Not a QMP code block + - Merely a preformatted code block literal + It isn't even an rST list. - *verbatim* - {braces} @@ -261,13 +260,11 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ + -> "this example" - -> in - - <- out + <- "has no title" "EVT_BOXED" (Event)