From nobody Fri May 3 17:22:33 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1558613745; cv=none; d=zoho.com; s=zohoarc; b=d6qKon05nKO1QCBh2HgHqd3nrcC58VZgOIG50t2kXjdAnhDQu7EE2FMEMUQIc2FvDgoISrtRSaxHhp7u2cE2LyZt8SEJagyNxIQSeqgV1bdwXCNX6eMcDFRa0+FcCvxHIauoApcIRNPZbHqmYmG+TXYen2/V20L2onocMhNA3IY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1558613745; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=JjpQaTQZSn/SIJ+tBf+HZUYZRIhQ0tQWv3gO1CYluRs=; b=FvJEkwxf7I39tEml0am/BVyAHLJjmmZMr+e4opLNHY6F8ppGDdnC0lQ08RNm4gIWPfHen0V/Q9tsc+8S7vC1A/QG/bKJFd1LSUBL16bX0PecYNCMbHr9d+U//CPcawog84IaTa/eTJJgEPryZ86vV6b0RCvJj5SazqnFG/4TvMs= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1558613745239405.2645577324548; Thu, 23 May 2019 05:15:45 -0700 (PDT) Received: from localhost ([127.0.0.1]:35074 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hTmca-0004At-8M for importer@patchew.org; Thu, 23 May 2019 08:14:56 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43338) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hTmag-00033S-FY for qemu-devel@nongnu.org; Thu, 23 May 2019 08:12:59 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hTmaf-0002Ih-FG for qemu-devel@nongnu.org; Thu, 23 May 2019 08:12:58 -0400 Received: from mx1.redhat.com ([209.132.183.28]:52224) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hTmad-0002Bm-0e; Thu, 23 May 2019 08:12:55 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 16A31309703F; Thu, 23 May 2019 12:12:36 +0000 (UTC) Received: from probe.bos.redhat.com (dhcp-17-187.bos.redhat.com [10.18.17.187]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4B22F795B3; Thu, 23 May 2019 12:12:35 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org, qemu-block@nongnu.org Date: Thu, 23 May 2019 08:12:29 -0400 Message-Id: <20190523121230.17193-2-jsnow@redhat.com> In-Reply-To: <20190523121230.17193-1-jsnow@redhat.com> References: <20190523121230.17193-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.43]); Thu, 23 May 2019 12:12:41 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 1/2] sphinx: add qmp_lexer X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Fam Zheng , Peter Maydell , John Snow , Eduardo Habkost , Aarushi Mehta Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" Sphinx, through Pygments, does not like annotated json examples very much. In some versions of Sphinx (1.7), it will render the non-json portions of code blocks in red, but in newer versions (2.0) it will throw an exception and not highlight the block at all. Though we can suppress this warning, it doesn't bring back highlighting on non-strict json blocks. We can alleviate this by creating a custom lexer for QMP examples that allows us to properly highlight these examples in a robust way, keeping our directionality notations. Signed-off-by: Eduardo Habkost Signed-off-by: John Snow Reviewed-by: Eduardo Habkost Reported-by: Aarushi Mehta --- docs/conf.py | 4 ++-- docs/sphinx/qmp_lexer.py | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 2 deletions(-) create mode 100644 docs/sphinx/qmp_lexer.py diff --git a/docs/conf.py b/docs/conf.py index befbcc6c3e..e46b299b71 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,7 +41,7 @@ except NameError: # add these directories to sys.path here. If the directory is relative to = the # documentation root, use an absolute path starting from qemu_docdir. # -# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir")) +sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) =20 =20 # -- General configuration ------------------------------------------------ @@ -54,7 +54,7 @@ needs_sphinx =3D '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions =3D [] +extensions =3D ['qmp_lexer'] =20 # Add any paths that contain templates here, relative to this directory. templates_path =3D ['_templates'] diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py new file mode 100644 index 0000000000..f3e6ea2585 --- /dev/null +++ b/docs/sphinx/qmp_lexer.py @@ -0,0 +1,34 @@ +# QEMU Monitor Protocol Lexer Extension +# +# Copyright (C) 2019, Red Hat Inc. +# +# Authors: +# Eduardo Habkost +# John Snow +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. +"""qmp_lexer is a Sphinx extension that provides a QMP lexer for code bloc= ks.""" + +from pygments.lexer import RegexLexer, DelegatingLexer +from pygments.lexers.data import JsonLexer +import pygments.token + +class QMPExampleMarkersLexer(RegexLexer): + """QMPExampleMarkersLexer lexes directionality flow indicators.""" + tokens =3D { + 'root': [ + (r'-> ', pygments.token.Generic.Prompt), + (r'<- ', pygments.token.Generic.Prompt), + ] + } + +class QMPExampleLexer(DelegatingLexer): + """QMPExampleLexer lexes annotated QMP examples.""" + def __init__(self, **options): + super(QMPExampleLexer, self).__init__(JsonLexer, QMPExampleMarkers= Lexer, + pygments.token.Error, **opti= ons) + +def setup(sphinx): + """For use by the Sphinx extensions API.""" + sphinx.add_lexer("QMP", QMPExampleLexer()) --=20 2.20.1 From nobody Fri May 3 17:22:33 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1558613715; cv=none; d=zoho.com; s=zohoarc; b=WZrdjNyg5kV90rpF2Idsg/Red8xXwXjJwuHxNo83+5p3z96VPghxP3eiLuBGJn+8fklacVu8vtMNF7U2zBMeuQxwY4xCf2ApKHkv/AxzpIY8WVtRk7kNlvIvoYYxmoD+AEHUtuevyeRY9bdEMEdXbpGgT4tC+U2fQp0SeAweI94= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1558613715; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=X39MUkjkonrW5YI4hzTo1k8V9lpicBOmlTSYcqbKRKA=; b=BT+0fDN/86zaSrZ45eJR4NF3WIGorbibvBlTk026XzZd2NdPMWJHMtrqKzJaYWgWNmYCQ957A4xD+n28gWI1yqSjEZbDOQiCVryKdaU1yI/NMeYjgZPyXpwyJTgYfn0UwZeGCxNJOmBKmchGP0Xb9KQqNqrrOr564xdDRr0JmU0= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (209.51.188.17 [209.51.188.17]) by mx.zohomail.com with SMTPS id 1558613715080194.0511542467957; Thu, 23 May 2019 05:15:15 -0700 (PDT) Received: from localhost ([127.0.0.1]:35076 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hTmcc-0004Cn-Ud for importer@patchew.org; Thu, 23 May 2019 08:14:58 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43362) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hTmal-00036K-1I for qemu-devel@nongnu.org; Thu, 23 May 2019 08:13:04 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hTmaj-0002Kw-NE for qemu-devel@nongnu.org; Thu, 23 May 2019 08:13:03 -0400 Received: from mx1.redhat.com ([209.132.183.28]:53616) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hTmag-0002DO-Kn; Thu, 23 May 2019 08:12:58 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id EC4ED307D989; Thu, 23 May 2019 12:12:39 +0000 (UTC) Received: from probe.bos.redhat.com (dhcp-17-187.bos.redhat.com [10.18.17.187]) by smtp.corp.redhat.com (Postfix) with ESMTP id 37B59795BA; Thu, 23 May 2019 12:12:36 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org, qemu-block@nongnu.org Date: Thu, 23 May 2019 08:12:30 -0400 Message-Id: <20190523121230.17193-3-jsnow@redhat.com> In-Reply-To: <20190523121230.17193-1-jsnow@redhat.com> References: <20190523121230.17193-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.48]); Thu, 23 May 2019 12:12:45 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 2/2] docs/bitmaps: use QMP lexer instead of json X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Fam Zheng , Peter Maydell , John Snow , Eduardo Habkost , Aarushi Mehta Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Type: text/plain; charset="utf-8" The annotated style json we use in QMP documentation is not strict json and depending on the version of Sphinx (2.0+) or Pygments installed, might cause the build to fail. Use the new QMP lexer. Further, some versions of Sphinx can not apply custom lexers to "code" directives and require the use of "code-block" directives instead, so make that change at this time as well. Tested under: - Sphinx 1.3.6 and Pygments 2.4 - Sphinx 1.7.6 and Pygments 2.2 - Sphinx 2.0.1 and Pygments 2.4 Reported-by: Aarushi Mehta Signed-off-by: John Snow Reviewed-by: Eduardo Habkost --- docs/interop/bitmaps.rst | 54 ++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/interop/bitmaps.rst b/docs/interop/bitmaps.rst index 510e8809a9..cf308f197b 100644 --- a/docs/interop/bitmaps.rst +++ b/docs/interop/bitmaps.rst @@ -199,7 +199,7 @@ persistence, and recording state can be adjusted at cre= ation time. =20 to create a new, actively recording persistent bitmap: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-add", "arguments": { @@ -220,7 +220,7 @@ persistence, and recording state can be adjusted at cre= ation time. To create a new, disabled (``-recording``), transient bitmap that tracks changes in 32KiB segments: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-add", "arguments": { @@ -254,7 +254,7 @@ Deletes a bitmap. Bitmaps that are ``+busy`` cannot be = removed. =20 Remove a bitmap named ``bitmap0`` from node ``drive0``: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-remove", "arguments": { @@ -280,7 +280,7 @@ Clears all dirty bits from a bitmap. ``+busy`` bitmaps = cannot be cleared. =20 Clear all dirty bits from bitmap ``bitmap0`` on node ``drive0``: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-clear", "arguments": { @@ -309,7 +309,7 @@ begin being recorded. ``+busy`` bitmaps cannot be enabl= ed. =20 To set ``+recording`` on bitmap ``bitmap0`` on node ``drive0``: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-enable", "arguments": { @@ -347,7 +347,7 @@ writes to begin being ignored. ``+busy`` bitmaps cannot= be disabled. =20 To set ``-recording`` on bitmap ``bitmap0`` on node ``drive0``: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-disable", "arguments": { @@ -393,7 +393,7 @@ in any one source bitmap, the target bitmap will mark t= hat segment dirty. ``drive0``. If ``new_bitmap`` was empty prior to this command, this achie= ves a copy. =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "block-dirty-bitmap-merge", "arguments": { @@ -424,7 +424,7 @@ attached to nodes serving as the root for guest devices. API. This result highlights a bitmap ``bitmap0`` attached to the root nod= e of device ``drive0``. =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "query-block", @@ -562,7 +562,7 @@ new, empty bitmap that records writes from this point i= n time forward. destination. These writes will be recorded in the bitmap accordingly. =20 -.. code:: json +.. code-block:: QMP =20 -> { "execute": "transaction", @@ -650,7 +650,7 @@ Example: Resetting an Incremental Backup Anchor Point If we want to start a new backup chain with an existing bitmap, we can also use a transaction to reset the bitmap while making a new full backup: =20 -.. code:: json +.. code-block:: QMP =20 -> { "execute": "transaction", @@ -730,7 +730,7 @@ Example: First Incremental Backup =20 #. Issue an incremental backup command: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "drive-backup", @@ -788,7 +788,7 @@ Example: Second Incremental Backup #. Issue a new incremental backup command. The only difference here is tha= t we have changed the target image below. =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "drive-backup", @@ -869,7 +869,7 @@ image: #. Issue a new incremental backup command. Apart from the new destination image, there is no difference from the last two examples. =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "drive-backup", @@ -932,7 +932,7 @@ point in time. =20 #. Create a full (anchor) backup for each drive, with accompanying bitmaps: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "transaction", @@ -1018,7 +1018,7 @@ point in time. =20 #. Issue a multi-drive incremental push backup transaction: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "transaction", @@ -1121,7 +1121,7 @@ described above. This example demonstrates the single= -job failure case: =20 #. Attempt to create an incremental backup via QMP: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "drive-backup", @@ -1139,7 +1139,7 @@ described above. This example demonstrates the single= -job failure case: =20 #. Receive a pair of events indicating failure: =20 - .. code:: json + .. code-block:: QMP =20 <- { "timestamp": {...}, @@ -1175,7 +1175,7 @@ described above. This example demonstrates the single= -job failure case: #. Retry the command after fixing the underlying problem, such as freeing up space on the backup volume: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "drive-backup", @@ -1193,7 +1193,7 @@ described above. This example demonstrates the single= -job failure case: =20 #. Receive confirmation that the job completed successfully: =20 - .. code:: json + .. code-block:: QMP =20 <- { "timestamp": {...}, @@ -1233,7 +1233,7 @@ and one succeeds: =20 #. Issue the transaction to start a backup of both drives. =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "transaction", @@ -1267,13 +1267,13 @@ and one succeeds: #. Receive notice that the Transaction was accepted, and jobs were launched: =20 - .. code:: json + .. code-block:: QMP =20 <- { "return": {} } =20 #. Receive notice that the first job has completed: =20 - .. code:: json + .. code-block:: QMP =20 <- { "timestamp": {...}, @@ -1289,7 +1289,7 @@ and one succeeds: =20 #. Receive notice that the second job has failed: =20 - .. code:: json + .. code-block:: QMP =20 <- { "timestamp": {...}, @@ -1365,7 +1365,7 @@ applied: =20 #. Issue the multi-drive incremental backup transaction: =20 - .. code:: json + .. code-block:: QMP =20 -> { "execute": "transaction", @@ -1401,13 +1401,13 @@ applied: =20 #. Receive notice that the Transaction was accepted, and jobs were launche= d: =20 - .. code:: json + .. code-block:: QMP =20 <- { "return": {} } =20 #. Receive notification that the backup job for ``drive1`` has failed: =20 - .. code:: json + .. code-block:: QMP =20 <- { "timestamp": {...}, @@ -1434,7 +1434,7 @@ applied: =20 #. Receive notification that the job for ``drive0`` has been cancelled: =20 - .. code:: json + .. code-block:: QMP =20 <- { "timestamp": {...} --=20 2.20.1