From patchwork Fri Sep 25 16:22:56 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371436 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=RTd8mKA/; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycgl2mJ1z9sRf for ; Sat, 26 Sep 2020 02:24:35 +1000 (AEST) Received: from localhost ([::1]:37418 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqWP-0006TV-6U for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:24:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47778) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVI-0006PT-EF for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:24 -0400 Received: from mail-wr1-x431.google.com ([2a00:1450:4864:20::431]:40792) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVG-0006ms-Bc for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:24 -0400 Received: by mail-wr1-x431.google.com with SMTP id j2so4218138wrx.7 for ; Fri, 25 Sep 2020 09:23:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=f3Y1p+WW0tVjbRnIDDuydFaNtzkRxU7Uq0iBhPhks/0=; b=RTd8mKA/+LdcjZQ+y7bRxAofNuJw16VSkhDUV2mRoEvX9NBzgbZomBumXHWa8NB7UF I88BVcd+qIymEGukHPMQmvRCu7PnqKR1WyBbTA/61u12Y4ZLqjU0LtCckj3KCQ99twZk xLGbJaPGWoMfaEW3JDOUQ5TDGdP4rekmaENNQLBO+fHT63Dmb16mhlfSmooNqTWt2ksu 9n+rmST5saUwA1DH3vS3BvJmzD3TuIiB0edvOiXoyppNlVKDB3xp8tvMl9yHWnwf9eyC 7YX1iK/Oq6vMg0YB6l6MCJvhsUEd3JvifGlCCUWsodVPG1CN0i/dPYZuaj4AcYYcr1In xFrg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=f3Y1p+WW0tVjbRnIDDuydFaNtzkRxU7Uq0iBhPhks/0=; b=k2hOFoTpAQRj6H63lYGIGAVRVbWKrKTUrcmq/lmUrCjADCzhdw8J6b27s7OEI+KMSx dyOjyWLvBVkROGdpXsYIntaT9LwGMca7vUJ0BNAB6Sd7EMTU0xceJyaRrTT/ABKDradr q/aJLBydA2YL2g/zy/v1jt0PiYoiNfoDpQF03NOdPvHNIoAoZmJac26iszZAzX0L0DaR 8joUB9Hl7oHhFqV7GTCTtn02r6pYKFEYGNhG8o6EgEJ+py1Oq+MRp+rrqnIaM0Rjbp/z F5aEYAp7IxWAtD6YKaBXBhLNZnilOd2IlYlz5Sgt2cl8cwAAOIAzsTiQoa/UaRg8B/NM X4ZA== X-Gm-Message-State: AOAM530wDhwFwJJ6IZucuGME/XPJRVvOVTBPUER6GY9s9dnMifmDh9ZP YYAkNLR/oShSfedB7ra/OndM0zZGsxuk9n8x X-Google-Smtp-Source: ABdhPJwBl4fThuNXxxbkJDsQwMQZ9y43Kq0oHMc4oPQK3Kbrrt9dyIzgPibzg1A7KduvHW6/sVr0gA== X-Received: by 2002:adf:8b1d:: with SMTP id n29mr5155248wra.383.1601050999311; Fri, 25 Sep 2020 09:23:19 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:18 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 01/21] qapi: Fix doc comment indentation again Date: Fri, 25 Sep 2020 17:22:56 +0100 Message-Id: <20200925162316.21205-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::431; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x431.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" In commit 26ec4e53f2 and similar commits we fixed the indentation for doc comments in our qapi json files to follow a new stricter standard for indentation, which permits only: @arg: description line 1 description line 2 or: @arg: line 1 line 2 but because the script updates that enforce this are not yet in the tree we have had a steady trickle of subsequent changes which didn't follow the new rules. Fix the latest round of mis-indented doc comments. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- qapi/block-core.json | 4 +- qapi/migration.json | 102 +++++++++++++++++++++---------------------- 2 files changed, 53 insertions(+), 53 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 3c16f1e11d6..dd77a91174c 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -4316,8 +4316,8 @@ # @data-file-raw: True if the external data file must stay valid as a # standalone (read-only) raw image without looking at qcow2 # metadata (default: false; since: 4.0) -# @extended-l2 True to make the image have extended L2 entries -# (default: false; since 5.2) +# @extended-l2: True to make the image have extended L2 entries +# (default: false; since 5.2) # @size: Size of the virtual disk in bytes # @version: Compatibility level (default: v3) # @backing-file: File name of the backing file if a backing file diff --git a/qapi/migration.json b/qapi/migration.json index 675f70bb673..b89052c6fd3 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -681,23 +681,23 @@ # Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such +# aliases may for example be the corresponding names on the +# opposite site. +# The mapping must be one-to-one, but not necessarily +# complete: On the source, unmapped bitmaps and all bitmaps +# on unmapped nodes will be ignored. On the destination, +# encountering an unmapped alias in the incoming migration +# stream will result in a report, and all further bitmap +# migration data will then be discarded. +# Note that the destination does not know about bitmaps it +# does not receive, so there is no limitation or requirement +# regarding the number of bitmaps received, or how they are +# named, or on which nodes they are placed. +# By default (when this parameter has never been set), bitmap +# names are mapped to themselves. Nodes are mapped to their +# block device name if there is one, and to their node name +# otherwise. (Since 5.2) # # Since: 2.4 ## @@ -841,23 +841,23 @@ # Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such +# aliases may for example be the corresponding names on the +# opposite site. +# The mapping must be one-to-one, but not necessarily +# complete: On the source, unmapped bitmaps and all bitmaps +# on unmapped nodes will be ignored. On the destination, +# encountering an unmapped alias in the incoming migration +# stream will result in a report, and all further bitmap +# migration data will then be discarded. +# Note that the destination does not know about bitmaps it +# does not receive, so there is no limitation or requirement +# regarding the number of bitmaps received, or how they are +# named, or on which nodes they are placed. +# By default (when this parameter has never been set), bitmap +# names are mapped to themselves. Nodes are mapped to their +# block device name if there is one, and to their node name +# otherwise. (Since 5.2) # # Since: 2.4 ## @@ -1037,23 +1037,23 @@ # Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such +# aliases may for example be the corresponding names on the +# opposite site. +# The mapping must be one-to-one, but not necessarily +# complete: On the source, unmapped bitmaps and all bitmaps +# on unmapped nodes will be ignored. On the destination, +# encountering an unmapped alias in the incoming migration +# stream will result in a report, and all further bitmap +# migration data will then be discarded. +# Note that the destination does not know about bitmaps it +# does not receive, so there is no limitation or requirement +# regarding the number of bitmaps received, or how they are +# named, or on which nodes they are placed. +# By default (when this parameter has never been set), bitmap +# names are mapped to themselves. Nodes are mapped to their +# block device name if there is one, and to their node name +# otherwise. (Since 5.2) # # Since: 2.4 ## From patchwork Fri Sep 25 16:22:57 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371439 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=Ly51b0ni; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byckh57jXz9ryj for ; Sat, 26 Sep 2020 02:27:08 +1000 (AEST) Received: from localhost ([::1]:46066 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqYs-0001oc-Di for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:27:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47798) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVJ-0006RJ-4z for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:25 -0400 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:50696) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVG-0006n4-EQ for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:24 -0400 Received: by mail-wm1-x341.google.com with SMTP id e17so3636916wme.0 for ; Fri, 25 Sep 2020 09:23:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=c4J/ihfjud0tiL/YgbEpbNjAusuDSDtTtmByqn5ExUo=; b=Ly51b0niAPdRMoO9pFuqtLIZV7yDCrCyGQaaCQNb8Rj0SiaYJJMn4/7IM+hGFFAi0S 9/3MBB34rS9Kpang7iFSXoZm7RnPQkNMjxEp1YtwrhdcrOZtOtyjFrv0tDJO+D4k+BLY 14BHQeSSX68yKI+ygYkqBMsCdIud6CYFESE/2VMcf0clA04aMgA33DjFzqGRYEuFzQ7T jLvcOh9Zlk9/59IcuISbes4Y0mhFSO2BrAHIkZBGBhp+ONOYsHuEcq/SIWaQyo3R5zEe 3jNsrntJY35yW5CHNl/VowQsBbTTr5WtCDuiM9DoywPgdCIxuW3tzodk9Rrl8FeWfkE7 KtGA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=c4J/ihfjud0tiL/YgbEpbNjAusuDSDtTtmByqn5ExUo=; b=Rn0lCxB6WlJw710Czxl39El/La5mQWuwgsgX9sBDoiNcu/ZOLKUS7HXmEkMQ2Y1/H4 TZY3hLiE9KZ8sgWXdQYpyMa01qq8sekI8KTgeXYqSireA9eGUtd7goap0d25g0ciyRS1 DPYNbL+TvQ9bf7LmlriH+CwAmmyiylSnWnyTT0SnyDTxd6KFNvYk3KRiazuTGUsdX8Xj jnuTNhk8G2D89diNkO2N1EjE1TTllKic9L2LZ//4VzfMVbmsV0sLE+SKEqxcre5riegJ spkWGsFzjKZn2cJZyOWICuDfNH9Opa7IdlaqYZMb1Gms6CRvB36KRPUfyQUdco6cdhMx fPVg== X-Gm-Message-State: AOAM530KTWdW0ZCHowjZ8+pNlWCmv54pdA0q6iKkGbvh1WkMwS66+Dd9 a4zOxmIBpLDFQtxZ7f4ScY26udBK5MgNCvWl X-Google-Smtp-Source: ABdhPJy0nKQ5ZSNNamO7SIg1g+TOg4lVO7fM5iGWxgVAkuilIEFlcAAnQvuSPCp6XB0qRltN3Q6iPg== X-Received: by 2002:a1c:800f:: with SMTP id b15mr3793482wmd.114.1601051000539; Fri, 25 Sep 2020 09:23:20 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:19 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 02/21] qapi/block.json: Add newline after "Example:" for block-latency-histogram-set Date: Fri, 25 Sep 2020 17:22:57 +0100 Message-Id: <20200925162316.21205-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::341; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x341.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" The block-latency-histogram-set command is the only one which uses the Example/Examples section with the first line of the documentation immediately following the ':'. Bring it into line with the rest. This allows us to avoid special-casing the indentation handling for "Examples" sections; instead for Examples as for any other section header these two indentations will be equivalent: Examples: Line one Line two Examples: Line one Line two Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- qapi/block.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/qapi/block.json b/qapi/block.json index c54a393cf3a..a009f7d3a2d 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -528,7 +528,8 @@ # # Since: 4.0 # -# Example: set new histograms for all io types with intervals +# Example: +# set new histograms for all io types with intervals # [0, 10), [10, 50), [50, 100), [100, +inf): # # -> { "execute": "block-latency-histogram-set", @@ -536,7 +537,8 @@ # "boundaries": [10, 50, 100] } } # <- { "return": {} } # -# Example: set new histogram only for write, other histograms will remain +# Example: +# set new histogram only for write, other histograms will remain # not changed (or not created): # # -> { "execute": "block-latency-histogram-set", @@ -544,7 +546,8 @@ # "boundaries-write": [10, 50, 100] } } # <- { "return": {} } # -# Example: set new histograms with the following intervals: +# Example: +# set new histograms with the following intervals: # read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) # write: [0, 1000), [1000, 5000), [5000, +inf) # @@ -554,7 +557,8 @@ # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # -# Example: remove all latency histograms: +# Example: +# remove all latency histograms: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } From patchwork Fri Sep 25 16:22:58 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371441 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=WqioRCOf; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycp23N8Vz9ryj for ; Sat, 26 Sep 2020 02:30:02 +1000 (AEST) Received: from localhost ([::1]:54576 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqbg-0005Ml-Cv for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:30:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47804) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVJ-0006TG-VM for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:25 -0400 Received: from mail-wm1-x32c.google.com ([2a00:1450:4864:20::32c]:39036) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVH-0006nA-JY for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:25 -0400 Received: by mail-wm1-x32c.google.com with SMTP id b79so3925128wmb.4 for ; Fri, 25 Sep 2020 09:23:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=28aaJgz0ty8/sYEIPpfI2vKzBd+chPmkWk9I0NSqY4U=; b=WqioRCOfWLsxsp81/p2JCCxH1vqj5S3zAWscXOPyGvgr/qp+0bSAIvFNasVTZGr9z2 zIGIafMq3D6fkr9zIiLmk8jhWGMcDFtgxRzmQutigVMuxa9uJnjRNhx7IGmZT+Dg/aNA uOibvBQRdDSzvDviWzWiMTG91WQvBGZiQ7KAu+d+fCPRcJ36lmGgkufz8nFiB9cvN7b3 xm/MPCNE3cFXlwziiNdKmDGCA6F0GDMRu55kiBWC1N1Up9HdzxowKr01ZjXl6UWaMAq3 GVML4bu/Xt3lK6lpmWPbF5xb0BSBHaLVsKgDSAJ2pIa+RboV0STP9jweR9gjqcra5Q2L bkMw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=28aaJgz0ty8/sYEIPpfI2vKzBd+chPmkWk9I0NSqY4U=; b=l8BJDfDAMon4/gAeGSjLbyAyqR0I53Jrxyk9UaYYLoNKCQ4f4jxL5TLEGdMbqFBYy6 wiSTHCuQWU39vs4iFtPvHUOSNkhOSSLfXuuFV1OtpBPLV91Sf2K/dnjXJ3+kcUzQw51x O38QcUMfHfuKGmsYHVu5OXaM15FvTjYYdbOFETcmLQAqzd/J7nTSmaz/bNYAeNcRMCsW zDTSA3s/WXvH55BRE1z0Dqht8E6lvHTgBH2w5lI2hIzcdo6AXNrzgo0ob+6tgkaQBHg0 ZyvtjGSn8Xt16IUytjvseJn/W7S4HPv7MmR1Si5iD9fP6NPcGtPS8awCLXBDT8GMLB5J hRgQ== X-Gm-Message-State: AOAM5308b7IjB5dd09b0D4Z8UrsFuhFlynyio+0+grQcquH4CkJBsyDD IAf+Nbl8iLkIBjR5+MZjcJbRG8/QScVBjQnr X-Google-Smtp-Source: ABdhPJzuET/4bR0sH1/ZLRz0mNavC3ja8ssuIBCfbEss0x71t/OGFP07cEcjnl80WVq1GDa1yU1lnQ== X-Received: by 2002:a1c:9c8c:: with SMTP id f134mr3950038wme.27.1601051001790; Fri, 25 Sep 2020 09:23:21 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:21 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 03/21] tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension Date: Fri, 25 Sep 2020 17:22:58 +0100 Message-Id: <20200925162316.21205-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32c; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32c.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" doc-good.json tests doc comment parser corner cases. We're about to largely replace it by a Sphinx extension, which will have different corner cases. Tweak the test so it passes both with the old parser and the Sphinx extension, by making it match the more restrictive rST syntax: * in a single list the bullet types must all match * lists must have leading and following blank lines * the rules on when and where indentation matters differ * the '|' example syntax is going to go away entirely, so stop testing it This will avoid the tests spuriously breaking when we tighten up the parser code in the following commits. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- tests/qapi-schema/doc-good.json | 25 +++++++++++++------------ tests/qapi-schema/doc-good.out | 12 ++++++------ tests/qapi-schema/doc-good.texi | 12 +++--------- 3 files changed, 22 insertions(+), 27 deletions(-) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 9da72a1f556..c6822145c49 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -12,25 +12,25 @@ # # *strong* _with emphasis_ # @var {in braces} +# # * List item one -# - Two, multiple +# * Two, multiple # lines # -# 3. Three -# Still in list +# * Three +# Still in list +# +# Not in list # -# Not in list # - Second list -# Note: still in list +# Note: still in list # # Note: not in list +# # 1. Third list # is numbered # -# - another item -# -# | example -# | multiple lines +# 2. another item # # Returns: the King # Since: the first age @@ -68,7 +68,7 @@ ## # @Base: # @base1: -# the first member +# the first member ## { 'struct': 'Base', 'data': { 'base1': 'Enum' } } @@ -116,7 +116,7 @@ ## # @Alternate: # @i: an integer -# @b is undocumented +# @b is undocumented # # Features: # @alt-feat: a feature @@ -134,7 +134,7 @@ # @arg1: the first argument # # @arg2: the second -# argument +# argument # # Features: # @cmd-feat1: a feature @@ -143,6 +143,7 @@ # Returns: @Object # TODO: frobnicate # Notes: +# # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam # diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index d78a424cd9d..acb00ade17b 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -75,25 +75,25 @@ doc freeform *strong* _with emphasis_ @var {in braces} + * List item one -- Two, multiple +* Two, multiple lines -3. Three +* Three Still in list Not in list + - Second list Note: still in list Note: not in list + 1. Third list is numbered -- another item - -| example -| multiple lines +2. another item Returns: the King Since: the first age diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index 7f28fb7a0fb..12808989ffb 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -6,6 +6,7 @@ @strong{strong} @emph{with emphasis} @code{var} @{in braces@} + @itemize @bullet @item List item one @@ -20,6 +21,7 @@ Still in list @end itemize Not in list + @itemize @minus @item Second list @@ -28,6 +30,7 @@ Note: still in list @end itemize Note: not in list + @enumerate @item Third list @@ -36,15 +39,6 @@ is numbered @item another item -@example -example -@end example - -@example -multiple lines -@end example - - @end enumerate Returns: the King From patchwork Fri Sep 25 16:22:59 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371438 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=zsjiq9QK; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byckg2zdcz9ryj for ; Sat, 26 Sep 2020 02:27:07 +1000 (AEST) Received: from localhost ([::1]:45942 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqYr-0001lb-Bq for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:27:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47830) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVL-0006WK-2S for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:27 -0400 Received: from mail-wm1-x333.google.com ([2a00:1450:4864:20::333]:55838) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVJ-0006nR-0d for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:26 -0400 Received: by mail-wm1-x333.google.com with SMTP id d4so3598733wmd.5 for ; Fri, 25 Sep 2020 09:23:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=sj15rBZcZbKv+lDFIRDA3aSKWbqE5DeyxJYs1f/78+s=; b=zsjiq9QKBCY7K0vEygnVbhoAWKBjuMR/fNFmwA80AtO9oEs9XMyzyD5DChesqOi8LT 6j35iJksBtkoklpg9RUMZHHyfnZNNl0vQAHBMj8D5TrJy8obrPqahaY2od0syyB32Gqy KR1kupSZNGZ5AnbRz2xEEPufT1WJeC2VMl0/fFaWOcwI54Xuzv5EpGapSrQGUr40l9ms cux2ydxMYnHOFM4e7exQuPRjUBt8PNPCzSbjOI9nhT6HO0aWUxr9Cj4P9LHe2NXsPY/H jHMq7MrU8mSFOP7Krruuatm97gRXS7yXUqRUENDSwjEhDGDg8gac6i41VQgXgPwEiW7z K6bw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=sj15rBZcZbKv+lDFIRDA3aSKWbqE5DeyxJYs1f/78+s=; b=KzPWvXk9HXBGKn/W5EEDX8nvY71KGKmtNp1VuQ6PLprivDJScu1sDUOAVQyqRTsa7h LquSw5Kgy3gxAteoqRbCHB/qFJBPcrFE/m58ZaV009TAVz4CN6UIjDLaa4yg1AZI6nSS biOB2oO+WJytYHtF2uWrPI5oZEksDGFRHBhC8G7qS5wMu7yMpWwaaLR7d/QOMc9rAagL b6IXTnCBnxgYCg/C3qP5yAZ5WvoJmTvTp7S32HSJGC5buIoDtg5GfAGPGNUFUBu+MJli CNntg/gD2HaYmswbADouhTSvAtSx5U6rka0NOCaAZCdoUSqjCxEKrDoeVA5S1k/jVI4X 4u+A== X-Gm-Message-State: AOAM532MldLkDgOTOrfWJP7zi0ey12uNMsFzuIrfkXTlR+DZJC5gzBxj 3Zrry2xk3pw1ExyMh6LVzBaEqRW3S5zs2L/7 X-Google-Smtp-Source: ABdhPJykv2BC6dB67kcxMP0frM9Ukqpw+RTiMZfkN2PBVBUIGvK5s5agvfFZ2Vernpc29axjcNzjGw== X-Received: by 2002:a1c:7907:: with SMTP id l7mr3925780wme.89.1601051002845; Fri, 25 Sep 2020 09:23:22 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:22 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 04/21] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Fri, 25 Sep 2020 17:22:59 +0100 Message-Id: <20200925162316.21205-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::333; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x333.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for Texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- tests/qapi-schema/doc-good.out | 12 ++++++------ 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 92f584edcf1..7764de1e4bc 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -79,6 +79,7 @@ def texi_format(doc): inlist = '' lastempty = False for line in doc.split('\n'): + line = line.strip() empty = line == '' # FIXME: Doing this in a single if / elif chain is diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 165925ca728..04bf10db378 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -427,10 +427,10 @@ class QAPIDoc: self._append_line = self._append_various_line self._append_various_line(line) else: - self._append_freeform(line.strip()) + self._append_freeform(line) else: # This is a free-form documentation block - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_args_line(self, line): """ @@ -463,7 +463,7 @@ class QAPIDoc: self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_features_line(self, line): name = line.split(' ', 1)[0] @@ -482,7 +482,7 @@ class QAPIDoc: self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_various_line(self, line): """ @@ -505,10 +505,6 @@ class QAPIDoc: line = line[len(name)+1:] self._start_section(name[:-1]) - if (not self._section.name or - not self._section.name.startswith('Example')): - line = line.strip() - self._append_freeform(line) def _start_symbol_section(self, symbols_dict, name): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index acb00ade17b..9993ffcd89d 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -78,20 +78,20 @@ doc freeform * List item one * Two, multiple -lines + lines * Three -Still in list + Still in list Not in list - Second list -Note: still in list + Note: still in list Note: not in list 1. Third list -is numbered + is numbered 2. another item @@ -159,7 +159,7 @@ doc symbol=Alternate arg=i an integer -@b is undocumented + @b is undocumented arg=b feature=alt-feat @@ -174,7 +174,7 @@ doc symbol=cmd the first argument arg=arg2 the second -argument + argument arg=arg3 feature=cmd-feat1 From patchwork Fri Sep 25 16:23:00 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371447 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=Xig6Zi/o; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycsl4WVJz9sR4 for ; Sat, 26 Sep 2020 02:33:15 +1000 (AEST) Received: from localhost ([::1]:34888 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqen-0000dB-IE for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:33:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47896) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVP-0006fm-Bq for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:31 -0400 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:36227) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVK-0006ng-56 for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:31 -0400 Received: by mail-wm1-x32f.google.com with SMTP id e2so3947418wme.1 for ; Fri, 25 Sep 2020 09:23:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=5QK61Iu51GnV8ssf6Wi/MgxNc0CZq3E5l2KB7srun8Y=; b=Xig6Zi/osi3xvMQQjBVOJASsu8Au2CYCGwRw2at+fLRXuA1I1ScdGES86h1PtIirfg Uicaae3CHoxcetyqlNXUOLoeMWdv9bXUZx6sVnCMy8p7OxQrT7j4QXLL/6JSJcdxVySq DWz9ENEDkjxvSc5BROGoB79P7CbfXfsTgBkdlsqSc5F++WbVgGLr1pl/zd16yMJvZwVm 5GAcmPxeYarmGb8RL77layYNW0Lx0Kga8LUR5C0UO4CwC12WysonUOynfraogrC1E/hd A1TI4Q7s7IumxCrQLGRYKzB8Bj3Uzho6O8hpaqepdMBSnoRwdTF0fwUg0fI05WykgN8j HXPQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=5QK61Iu51GnV8ssf6Wi/MgxNc0CZq3E5l2KB7srun8Y=; b=Cz7Q4e24Vc3FebgIdd55wB2+fr2nfBFMUd19HCEoUOnk6rZFBfg/FeuKomFFeWXfph Ei6O3mqXxDZAYuXZ7PYMt3UTeA920alOpCW7VsTNHqKjNWWjgGhx2noW9020BmIol1lx yRZOyQS4SkChKuklieDStlw4/NP7u2+1scA83rSPpNfwsuioDOtKZaMnIk5AZKJQU7PE xie5dGji3YgBdKk2MCNuhabW3gj1IyqFUDwxMICdBpo/um3Swy28oxojjdZdFOWeMnkM Ocktut+dhJs/em/vchyAjL9uy/uDW4/Qs4p9z/hM1njSUQVI7UaBOF2wr5peSkxgBbtJ HhSw== X-Gm-Message-State: AOAM530IPic3VExq0/CO9IwpKwl4sI5kHTXYBnRilAWPZjuw8zP9cuUF xEDX9GOD42duQT40q4vxUCyFxtejJ4y7+32U X-Google-Smtp-Source: ABdhPJwzi7k5Xe1+M7y5Z+vrD5sccG0rJY/YKaSOM9RH5tVygubJPS9DC62ltFDmhJ+QndM4GN62gA== X-Received: by 2002:a05:600c:2283:: with SMTP id 3mr3826443wmf.37.1601051004050; Fri, 25 Sep 2020 09:23:24 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:23 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 05/21] scripts/qapi/parser.py: improve doc comment indent handling Date: Fri, 25 Sep 2020 17:23:00 +0100 Message-Id: <20200925162316.21205-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32f; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32f.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) The golden reference for the doc comment text is updated to remove the two 'wrong' indents; these now form a test case that we correctly stripped leading whitespace from an indented multi-line argument definition. We update the documentation in docs/devel/qapi-code-gen.txt to describe the new indentation rules. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 23 +++++++ scripts/qapi/parser.py | 93 +++++++++++++++++++++------ tests/qapi-schema/doc-bad-indent.err | 1 + tests/qapi-schema/doc-bad-indent.json | 8 +++ tests/qapi-schema/doc-bad-indent.out | 0 tests/qapi-schema/doc-good.out | 4 +- tests/qapi-schema/meson.build | 1 + 7 files changed, 109 insertions(+), 21 deletions(-) create mode 100644 tests/qapi-schema/doc-bad-indent.err create mode 100644 tests/qapi-schema/doc-bad-indent.json create mode 100644 tests/qapi-schema/doc-bad-indent.out diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 9eede44350c..69eaffac376 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -901,6 +901,22 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), and finally optional tagged sections. +Descriptions of arguments can span multiple lines. The description +text can start on the line following the '@argname:', in which case +it must not be indented at all. It can also start on the same line +as the '@argname:'. In this case if it spans multiple lines then +second and subsequent lines must be indented to line up with the +first character of the first line of the description: + +# @argone: +# This is a two line description +# in the first style. +# +# @argtwo: This is a two line description +# in the second style. + +The number of spaces between the ':' and the text is not significant. + FIXME: the parser accepts these things in almost any order. FIXME: union branches should be described, too. @@ -911,6 +927,13 @@ A tagged section starts with one of the following words: "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". The section ends with the start of a new section. +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first, in the same way as +multiline argument descriptions. + A 'Since: x.y.z' tagged section lists the release that introduced the definition. diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 04bf10db378..6c3455b41f3 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -319,17 +319,32 @@ class QAPIDoc: """ class Section: - def __init__(self, name=None): + def __init__(self, parser, name=None, indent=0): + # parser, for error messages about indentation + self._parser = parser # optional section name (argument/member or section name) self.name = name self.text = '' + # the expected indent level of the text of this section + self._indent = indent def append(self, line): + # Strip leading spaces corresponding to the expected indent level + # Blank lines are always OK. + if line: + indent = re.match(r'\s*', line).end() + if indent < self._indent: + raise QAPIParseError( + self._parser, + "unexpected de-indent (expected at least %d spaces)" % + self._indent) + line = line[self._indent:] + self.text += line.rstrip() + '\n' class ArgSection(Section): - def __init__(self, name): - super().__init__(name) + def __init__(self, parser, name, indent=0): + super().__init__(parser, name, indent) self.member = None def connect(self, member): @@ -343,7 +358,7 @@ class QAPIDoc: self._parser = parser self.info = info self.symbol = None - self.body = QAPIDoc.Section() + self.body = QAPIDoc.Section(parser) # dict mapping parameter name to ArgSection self.args = OrderedDict() self.features = OrderedDict() @@ -447,8 +462,21 @@ class QAPIDoc: name = line.split(' ', 1)[0] if name.startswith('@') and name.endswith(':'): - line = line[len(name)+1:] - self._start_args_section(name[1:-1]) + # If line is "@arg: first line of description", find the + # index of 'f', which is the indent we expect for any + # following lines. We then remove the leading "@arg:" from line + # and replace it with spaces so that 'f' has the same index + # as it did in the original line and can be handled the same + # way we will handle following lines. + indent = re.match(r'@\S*:\s*', line).end() + line = line[indent:] + if not line: + # Line was just the "@arg:" header; following lines + # are not indented + indent = 0 + else: + line = ' ' * indent + line + self._start_args_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line = self._append_various_line self._append_various_line(line) @@ -469,8 +497,21 @@ class QAPIDoc: name = line.split(' ', 1)[0] if name.startswith('@') and name.endswith(':'): - line = line[len(name)+1:] - self._start_features_section(name[1:-1]) + # If line is "@arg: first line of description", find the + # index of 'f', which is the indent we expect for any + # following lines. We then remove the leading "@arg:" from line + # and replace it with spaces so that 'f' has the same index + # as it did in the original line and can be handled the same + # way we will handle following lines. + indent = re.match(r'@\S*:\s*', line).end() + line = line[indent:] + if not line: + # Line was just the "@arg:" header; following lines + # are not indented + indent = 0 + else: + line = ' ' * indent + line + self._start_features_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line = self._append_various_line self._append_various_line(line) @@ -502,12 +543,25 @@ class QAPIDoc: "'%s' can't follow '%s' section" % (name, self.sections[0].name)) if self._is_section_tag(name): - line = line[len(name)+1:] - self._start_section(name[:-1]) + # If line is "Section: first line of description", find the + # index of 'f', which is the indent we expect for any + # following lines. We then remove the leading "Section:" from line + # and replace it with spaces so that 'f' has the same index + # as it did in the original line and can be handled the same + # way we will handle following lines. + indent = re.match(r'\S*:\s*', line).end() + line = line[indent:] + if not line: + # Line was just the "Section:" header; following lines + # are not indented + indent = 0 + else: + line = ' ' * indent + line + self._start_section(name[:-1], indent) self._append_freeform(line) - def _start_symbol_section(self, symbols_dict, name): + def _start_symbol_section(self, symbols_dict, name, indent): # FIXME invalid names other than the empty string aren't flagged if not name: raise QAPIParseError(self._parser, "invalid parameter name") @@ -516,21 +570,21 @@ class QAPIDoc: "'%s' parameter name duplicated" % name) assert not self.sections self._end_section() - self._section = QAPIDoc.ArgSection(name) + self._section = QAPIDoc.ArgSection(self._parser, name, indent) symbols_dict[name] = self._section - def _start_args_section(self, name): - self._start_symbol_section(self.args, name) + def _start_args_section(self, name, indent): + self._start_symbol_section(self.args, name, indent) - def _start_features_section(self, name): - self._start_symbol_section(self.features, name) + def _start_features_section(self, name, indent): + self._start_symbol_section(self.features, name, indent) - def _start_section(self, name=None): + def _start_section(self, name=None, indent=0): if name in ('Returns', 'Since') and self.has_section(name): raise QAPIParseError(self._parser, "duplicated '%s' section" % name) self._end_section() - self._section = QAPIDoc.Section(name) + self._section = QAPIDoc.Section(self._parser, name, indent) self.sections.append(self._section) def _end_section(self): @@ -553,7 +607,8 @@ class QAPIDoc: def connect_member(self, member): if member.name not in self.args: # Undocumented TODO outlaw - self.args[member.name] = QAPIDoc.ArgSection(member.name) + self.args[member.name] = QAPIDoc.ArgSection(self._parser, + member.name) self.args[member.name].connect(member) def connect_feature(self, feature): diff --git a/tests/qapi-schema/doc-bad-indent.err b/tests/qapi-schema/doc-bad-indent.err new file mode 100644 index 00000000000..67844539bd2 --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.err @@ -0,0 +1 @@ +doc-bad-indent.json:6:1: unexpected de-indent (expected at least 4 spaces) diff --git a/tests/qapi-schema/doc-bad-indent.json b/tests/qapi-schema/doc-bad-indent.json new file mode 100644 index 00000000000..edde8f21dc7 --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.json @@ -0,0 +1,8 @@ +# Multiline doc comments should have consistent indentation + +## +# @foo: +# @a: line one +# line two is wrongly indented +## +{ 'command': 'foo', 'data': { 'a': 'int' } } diff --git a/tests/qapi-schema/doc-bad-indent.out b/tests/qapi-schema/doc-bad-indent.out new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 9993ffcd89d..b7e3f4313da 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -159,7 +159,7 @@ doc symbol=Alternate arg=i an integer - @b is undocumented +@b is undocumented arg=b feature=alt-feat @@ -174,7 +174,7 @@ doc symbol=cmd the first argument arg=arg2 the second - argument +argument arg=arg3 feature=cmd-feat1 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index f1449298b07..83a0a68389b 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -53,6 +53,7 @@ schemas = [ 'doc-bad-enum-member.json', 'doc-bad-event-arg.json', 'doc-bad-feature.json', + 'doc-bad-indent.json', 'doc-bad-section.json', 'doc-bad-symbol.json', 'doc-bad-union-member.json', From patchwork Fri Sep 25 16:23:01 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371449 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=hgqentZ6; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byct0301Yz9ryj for ; Sat, 26 Sep 2020 02:33:28 +1000 (AEST) Received: from localhost ([::1]:35984 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqey-00014i-6d for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:33:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47852) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVM-0006ao-Gh for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:28 -0400 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:43317) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVK-0006nl-Mt for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:28 -0400 Received: by mail-wr1-x441.google.com with SMTP id k15so4191666wrn.10 for ; Fri, 25 Sep 2020 09:23:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=VdZoU9e76kBSToXFVSJBVTmzL794wmNQ6KcV8zhQ7b4=; b=hgqentZ6khbnd6AymvelNIDUhwdbfYAEnXEI+BtAb1q7Rc3+kgO6ud70hOqkSq/0cl zHMawED5WhPTUXwa+89A8N+ZiBmCt1vbhRlA6YKk9mn9wfEaeHmjPPsMj9lHrB0j0G0n TdO5NadrjLPVS4VoMuNp8Fx90B+54tjMHX4WI6rx0Hc4TCjtn/4OVAnnbC3a0EqcNVFg WH1F+e8NfPXq/rHlRwgkreVhC0tcUONoZUyFWm0mK+4DpzYopJa42f+0WRE047jf4Eja EQIh7pKdiDLikGik1XJPLlYqXf0jmyOXNVH78V7+MVhgle3MoKPvDEepRVlKdKXrvw/C +D0w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=VdZoU9e76kBSToXFVSJBVTmzL794wmNQ6KcV8zhQ7b4=; b=BYHo6VimWj3HDuBftK8FrcJRozsiwvlNo1/xiFMh+GNgJsZORiGUeNjAVy77FkBM/q rgSKU0XrHxBNu7msh3oZhiEw2F1kT7GCgimDSA8zs6pnAYIcsVNeKriK1juj5QU+BWAk 7CPyi5aXL9LcyefYGX75dCbZCik0Y+x9s2ZqNJ0hVIjSogarU+3mLKLvuQPNvZPvkaDp eAJCkoxbZFQYGQf9StuslREnCqqG8I1zObdQfqYzaXbcF/5fipQNKTbbmqLTmu5brGt4 /y5wjrdWxBwGu5Y876b3ECL8DopnR/JQtKSbTfXzTgVW0VmUmJ9uswdXCSzKZriD8m29 ubbw== X-Gm-Message-State: AOAM530GKcsX6NeVikoicw513gmuEEO7ADvzvDQLCvYkie0yxc6jiZNz KT6SYvw4g9v0rViNEe/kIA9LOfAT3PA6i2t+ X-Google-Smtp-Source: ABdhPJwNSMLT6kSE8jCC8mah4/1KBNfT1WZvvm9uygtr0joveaeiDV027UiFnqNDW5+S+lAT250UCw== X-Received: by 2002:adf:a35d:: with SMTP id d29mr5326261wrb.307.1601051004929; Fri, 25 Sep 2020 09:23:24 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:24 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 06/21] qapi/machine.json: Escape a literal '*' in doc comment Date: Fri, 25 Sep 2020 17:23:01 +0100 Message-Id: <20200925162316.21205-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::441; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x441.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" For rST, '*' is a kind of inline markup (for emphasis), so "*-softmmu" is a syntax error because of the missing closing '*'. Escape the '*' with a '\'. The texinfo document generator will leave the '\' in the output, which is not ideal, but that generator is going to go away in a subsequent commit. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- qapi/machine.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/machine.json b/qapi/machine.json index 0ac1880e4a4..9c45b04363c 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -13,7 +13,7 @@ # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and -# look for the *-softmmu targets near the "--target-list" option. The +# look for the \*-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. # From patchwork Fri Sep 25 16:23:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371448 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=OpNFWEmb; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycsm1mRpz9sSJ for ; Sat, 26 Sep 2020 02:33:16 +1000 (AEST) Received: from localhost ([::1]:34974 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqeo-0000fI-6H for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:33:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47912) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVQ-0006h5-BC for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:33 -0400 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:46331) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVN-0006oJ-1n for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:32 -0400 Received: by mail-wr1-x435.google.com with SMTP id o5so4176388wrn.13 for ; Fri, 25 Sep 2020 09:23:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=R/80RuyH5u5+29BIDIq5/M73E0CR5x1sAdUqL1ir0qA=; b=OpNFWEmb+vzB+62xjIL03BQ0hOUZeFQ+J2BGpv2pLBQRIHO6i5NR64A1Igv9TGo9xV /YvcwCt8HEveic8WbHzdLQsFP7OwOcqSJEX0FIIzNt+P9rpOifrveyi268sCAxew6lNt 6Dp4ZvzxaqWyfifGChtIWfIrFrMG07L5VszaJgIlMeEqV/WWOZQ+tWuslpcTXr1pHYzi 17nIsZ3G1ui2jSrZl9DpHNT0YSUjsAGgm5Cpo6H8q+1SQEdJzyGNy5s73sruMrvwq2pZ 3NzzeCStBjuMA9s5oM2S3nonNf9qdJd2fkuhj55kOPFpP+uYbngds4QWCp49+tYWs9QX qEmA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=R/80RuyH5u5+29BIDIq5/M73E0CR5x1sAdUqL1ir0qA=; b=bjcuA0UtrqCKBHMuFTiR7BmWABbP1w3X9pgSssvQfEf30RoM8+Krr4+2513QfFNeBw CSMVtAVhPJq+4aOgYUue80kb7a7TPpmVoy/fKYmwQmJnudBwB5g+/MNcQZBBBaQQNG6a 15MiOXtdB43Y+BeZhfGcMKeN8XJINOA3J3GaNw6/Vnz6+3vj8spoZfjXRmtXiIWJlyjd fqnSb7Ujj0J6XT65dHWzQv/Bfu/dgxCnagCjQDa+OwR7oxTQIXS4+JkRud4QAmx3FVfI 6ndrOwao9qoiIju7fNBFpspA9hALvay0dT7yh+JCDgDYYFeTuhFgVX94cOrGVra6J/g0 qCnw== X-Gm-Message-State: AOAM5330Vc7MF8IWIlGQu63029GbdI4tTSLbDbONhMs0eUd0Sloi78KF haNrygpmJyhBkVWxuDdMjzvAZiKD6T8Wm9yI X-Google-Smtp-Source: ABdhPJz9QifdcyFG0GNSo9dUJP9CFVXkvrzttqnVeE66YDb4QmaadL1MKfyPba0SL9zrmqMkvP1hEA== X-Received: by 2002:adf:f984:: with SMTP id f4mr5391692wrr.102.1601051006666; Fri, 25 Sep 2020 09:23:26 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:26 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 07/21] docs/sphinx: Add new qapi-doc Sphinx extension Date: Fri, 25 Sep 2020 17:23:02 +0100 Message-Id: <20200925162316.21205-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::435; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x435.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- docs/conf.py | 6 +- docs/sphinx/qapidoc.py | 550 +++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 3 files changed, 556 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapidoc.py diff --git a/docs/conf.py b/docs/conf.py index 0dbd90dc112..606f623211d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,7 +52,10 @@ 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. # +# Our extensions are in docs/sphinx; the qapidoc extension requires +# the QAPI modules from scripts/. sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) +sys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) # -- General configuration ------------------------------------------------ @@ -67,7 +70,7 @@ needs_sphinx = '1.6' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile'] +extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -241,3 +244,4 @@ texinfo_documents = [ kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc') kerneldoc_srctree = os.path.join(qemu_docdir, '..') hxtool_srctree = os.path.join(qemu_docdir, '..') +qapidoc_srctree = os.path.join(qemu_docdir, '..') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py new file mode 100644 index 00000000000..afc4167f8b1 --- /dev/null +++ b/docs/sphinx/qapidoc.py @@ -0,0 +1,550 @@ +# coding=utf-8 +# +# QEMU qapidoc QAPI file parsing extension +# +# Copyright (c) 2020 Linaro +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. +"""qapidoc is a Sphinx extension that implements the qapi-doc directive""" + +# The purpose of this extension is to read the documentation comments +# in QAPI schema files, and insert them all into the current document. +# +# It implements one new rST directive, "qapi-doc::". +# Each qapi-doc:: directive takes one argument, which is the +# pathname of the schema file to process, relative to the source tree. +# +# The docs/conf.py file must set the qapidoc_srctree config value to +# the root of the QEMU source tree. +# +# The Sphinx documentation on writing extensions is at: +# https://www.sphinx-doc.org/en/master/development/index.html +import os +import re + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles +import sphinx +from qapi.gen import QAPISchemaVisitor +from qapi.schema import QAPIError, QAPISemError, QAPISchema + +# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later +# use switch_source_input. Check borrowed from kerneldoc.py. +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + + +__version__ = '1.0' + + +# Function borrowed from pydash, which is under the MIT license +def intersperse(iterable, separator): + """Yield the members of *iterable* interspersed with *separator*.""" + iterable = iter(iterable) + yield next(iterable) + for item in iterable: + yield separator + yield item + + +class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which generates docutils/Sphinx nodes + + This class builds up a tree of docutils/Sphinx nodes corresponding + to documentation for the various QAPI objects. To use it, first create + a QAPISchemaGenRSTVisitor object, and call its visit_begin() method. + Then you can call one of the two methods 'freeform' (to add documentation + for a freeform documentation chunk) or 'symbol' (to add documentation + for a QAPI symbol). These will cause the visitor to build up the + tree of document nodes. Once you've added all the documentation + via 'freeform' and 'symbol' method calls, you can call 'get_document_nodes' + to get the final list of document nodes (in a form suitable for returning + from a Sphinx directive's 'run' method). + """ + def __init__(self, sphinx_directive): + self._cur_doc = None + self._sphinx_directive = sphinx_directive + self._top_node = nodes.section() + self._active_headings = [self._top_node] + + def _serror(self, msg): + """Raise an exception giving a user-friendly syntax error message""" + file = self._cur_doc.info.fname + line = self._cur_doc.info.line + raise ExtensionError( + '%s line %d: syntax error: %s' % (file, line, msg)) + + def _make_dlitem(self, term, defn): + """Return a dlitem node with the specified term and definition. + + term should be a list of Text and literal nodes. + defn should be one of: + - a string, which will be handed to _parse_text_into_node + - a list of Text and literal nodes, which will be put into + a paragraph node + """ + dlitem = nodes.definition_list_item() + dlterm = nodes.term('', '', *term) + dlitem += dlterm + if defn: + dldef = nodes.definition() + if isinstance(defn, list): + dldef += nodes.paragraph('', '', *defn) + else: + self._parse_text_into_node(defn, dldef) + dlitem += dldef + return dlitem + + def _make_section(self, title): + """Return a section node with optional title""" + section = nodes.section(ids=[self._sphinx_directive.new_serialno()]) + if title: + section += nodes.title(title, title) + return section + + def _nodes_for_ifcond(self, ifcond, with_if=True): + """Return list of Text, literal nodes for the ifcond + + Return a list which gives text like ' (If: cond1, cond2, cond3)', where + the conditions are in literal-text and the commas are not. + If with_if is False, we don't return the "(If: " and ")". + """ + condlist = intersperse([nodes.literal('', c) for c in ifcond], + nodes.Text(', ')) + if not with_if: + return condlist + + nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')] + nodelist.extend(condlist) + nodelist.append(nodes.Text(')')) + return nodelist + + def _nodes_for_one_member(self, member): + """Return list of Text, literal nodes for this member + + Return a list of doctree nodes which give text like + 'name: type (optional) (If: ...)' suitable for use as the + 'term' part of a definition list item. + """ + term = [nodes.literal('', member.name)] + if member.type.doc_type(): + term.append(nodes.Text(': ')) + term.append(nodes.literal('', member.type.doc_type())) + if member.optional: + term.append(nodes.Text(' (optional)')) + if member.ifcond: + term.extend(self._nodes_for_ifcond(member.ifcond)) + return term + + def _nodes_for_variant_when(self, variants, variant): + """Return list of Text, literal nodes for variant 'when' clause + + Return a list of doctree nodes which give text like + 'when tagname is variant (If: ...)' suitable for use in + the 'variants' part of a definition list. + """ + term = [nodes.Text(' when '), + nodes.literal('', variants.tag_member.name), + nodes.Text(' is '), + nodes.literal('', '"%s"' % variant.name)] + if variant.ifcond: + term.extend(self._nodes_for_ifcond(variant.ifcond)) + return term + + def _nodes_for_members(self, doc, what, base=None, variants=None): + """Return list of doctree nodes for the table of members""" + dlnode = nodes.definition_list() + for section in doc.args.values(): + term = self._nodes_for_one_member(section.member) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn = section.text + elif (variants and variants.tag_member == section.member + and not section.member.type.doc_type()): + values = section.member.type.member_names() + defn = [nodes.Text('One of ')] + defn.extend(intersperse([nodes.literal('', v) for v in values], + nodes.Text(', '))) + else: + defn = [nodes.Text('Not documented')] + + dlnode += self._make_dlitem(term, defn) + + if base: + dlnode += self._make_dlitem([nodes.Text('The members of '), + nodes.literal('', base.doc_type())], + None) + + if variants: + for v in variants.variants: + if v.type.is_implicit(): + assert not v.type.base and not v.type.variants + for m in v.type.local_members: + term = self._nodes_for_one_member(m) + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) + else: + term = [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) + + if not dlnode.children: + return [] + + section = self._make_section(what) + section += dlnode + return [section] + + def _nodes_for_enum_values(self, doc): + """Return list of doctree nodes for the table of enum values""" + seen_item = False + dlnode = nodes.definition_list() + for section in doc.args.values(): + termtext = [nodes.literal('', section.member.name)] + if section.member.ifcond: + termtext.extend(self._nodes_for_ifcond(section.member.ifcond)) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn = section.text + else: + defn = [nodes.Text('Not documented')] + + dlnode += self._make_dlitem(termtext, defn) + seen_item = True + + if not seen_item: + return [] + + section = self._make_section('Values') + section += dlnode + return [section] + + def _nodes_for_arguments(self, doc, boxed_arg_type): + """Return list of doctree nodes for the arguments section""" + if boxed_arg_type: + assert not doc.args + section = self._make_section('Arguments') + dlnode = nodes.definition_list() + dlnode += self._make_dlitem( + [nodes.Text('The members of '), + nodes.literal('', boxed_arg_type.name)], + None) + section += dlnode + return [section] + + return self._nodes_for_members(doc, 'Arguments') + + def _nodes_for_features(self, doc): + """Return list of doctree nodes for the table of features""" + seen_item = False + dlnode = nodes.definition_list() + for section in doc.features.values(): + dlnode += self._make_dlitem([nodes.literal('', section.name)], + section.text) + seen_item = True + + if not seen_item: + return [] + + section = self._make_section('Features') + section += dlnode + return [section] + + def _nodes_for_example(self, exampletext): + """Return list of doctree nodes for a code example snippet""" + return [nodes.literal_block(exampletext, exampletext)] + + def _nodes_for_sections(self, doc): + """Return list of doctree nodes for additional sections""" + nodelist = [] + for section in doc.sections: + snode = self._make_section(section.name) + if section.name and section.name.startswith('Example'): + snode += self._nodes_for_example(section.text) + else: + self._parse_text_into_node(section.text, snode) + nodelist.append(snode) + return nodelist + + def _nodes_for_if_section(self, ifcond): + """Return list of doctree nodes for the "If" section""" + nodelist = [] + if ifcond: + snode = self._make_section('If') + snode += self._nodes_for_ifcond(ifcond, with_if=False) + nodelist.append(snode) + return nodelist + + def _add_doc(self, typ, sections): + """Add documentation for a command/object/enum... + + We assume we're documenting the thing defined in self._cur_doc. + typ is the type of thing being added ("Command", "Object", etc) + + sections is a list of nodes for sections to add to the definition. + """ + + doc = self._cur_doc + snode = nodes.section(ids=[self._sphinx_directive.new_serialno()]) + snode += nodes.title('', '', *[nodes.literal(doc.symbol, doc.symbol), + nodes.Text(' (' + typ + ')')]) + self._parse_text_into_node(doc.body.text, snode) + for s in sections: + if s is not None: + snode += s + self._add_node_to_current_heading(snode) + + def visit_enum_type(self, name, info, ifcond, features, members, prefix): + doc = self._cur_doc + self._add_doc('Enum', + self._nodes_for_enum_values(doc) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_object_type(self, name, info, ifcond, features, + base, members, variants): + doc = self._cur_doc + if base and base.is_implicit(): + base = None + self._add_doc('Object', + self._nodes_for_members(doc, 'Members', base, variants) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_alternate_type(self, name, info, ifcond, features, variants): + doc = self._cur_doc + self._add_doc('Alternate', + self._nodes_for_members(doc, 'Members') + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_command(self, name, info, ifcond, features, arg_type, + ret_type, gen, success_response, boxed, allow_oob, + allow_preconfig): + doc = self._cur_doc + self._add_doc('Command', + self._nodes_for_arguments(doc, + arg_type if boxed else None) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_event(self, name, info, ifcond, features, arg_type, boxed): + doc = self._cur_doc + self._add_doc('Event', + self._nodes_for_arguments(doc, + arg_type if boxed else None) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def symbol(self, doc, entity): + """Add documentation for one symbol to the document tree + + This is the main entry point which causes us to add documentation + nodes for a symbol (which could be a 'command', 'object', 'event', + etc). We do this by calling 'visit' on the schema entity, which + will then call back into one of our visit_* methods, depending + on what kind of thing this symbol is. + """ + self._cur_doc = doc + entity.visit(self) + self._cur_doc = None + + def _start_new_heading(self, heading, level): + """Start a new heading at the specified heading level + + Create a new section whose title is 'heading' and which is placed + in the docutils node tree as a child of the most recent level-1 + heading. Subsequent document sections (commands, freeform doc chunks, + etc) will be placed as children of this new heading section. + """ + if len(self._active_headings) < level: + raise QAPISemError(self._cur_doc.info, + 'Level %d subheading found outside a ' + 'level %d heading' + % (level, level - 1)) + snode = self._make_section(heading) + self._active_headings[level - 1] += snode + self._active_headings = self._active_headings[:level] + self._active_headings.append(snode) + + def _add_node_to_current_heading(self, node): + """Add the node to whatever the current active heading is""" + self._active_headings[-1] += node + + def freeform(self, doc): + """Add a piece of 'freeform' documentation to the document tree + + A 'freeform' document chunk doesn't relate to any particular + symbol (for instance, it could be an introduction). + + If the freeform document starts with a line of the form + '= Heading text', this is a section or subsection heading, with + the heading level indicated by the number of '=' signs. + """ + + # QAPIDoc documentation says free-form documentation blocks + # must have only a body section, nothing else. + assert not doc.sections + assert not doc.args + assert not doc.features + self._cur_doc = doc + + text = doc.body.text + if re.match(r'=+ ', text): + # Section/subsection heading (if present, will always be + # the first line of the block) + (heading, _, text) = text.partition('\n') + (leader, _, heading) = heading.partition(' ') + self._start_new_heading(heading, len(leader)) + if text == '': + return + + node = self._make_section(None) + self._parse_text_into_node(text, node) + self._add_node_to_current_heading(node) + self._cur_doc = None + + def _parse_text_into_node(self, doctext, node): + """Parse a chunk of QAPI-doc-format text into the node + + The doc comment can contain most inline rST markup, including + bulleted and enumerated lists. + As an extra permitted piece of markup, @var will be turned + into ``var``. + """ + + # Handle the "@var means ``var`` case + doctext = re.sub(r'@([\w-]+)', r'``\1``', doctext) + + rstlist = ViewList() + for line in doctext.splitlines(): + # The reported line number will always be that of the start line + # of the doc comment, rather than the actual location of the error. + # Being more precise would require overhaul of the QAPIDoc class + # to track lines more exactly within all the sub-parts of the doc + # comment, as well as counting lines here. + rstlist.append(line, self._cur_doc.info.fname, + self._cur_doc.info.line) + # Append a blank line -- in some cases rST syntax errors get + # attributed to the line after one with actual text, and if there + # isn't anything in the ViewList corresponding to that then Sphinx + # 1.6's AutodocReporter will then misidentify the source/line location + # in the error message (usually attributing it to the top-level + # .rst file rather than the offending .json file). The extra blank + # line won't affect the rendered output. + rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.line) + self._sphinx_directive.do_parse(rstlist, node) + + def get_document_nodes(self): + """Return the list of docutils nodes which make up the document""" + return self._top_node.children + + +class QAPISchemaGenDepVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which adds Sphinx dependencies each module + + This class calls the Sphinx note_dependency() function to tell Sphinx + that the generated documentation output depends on the input + schema file associated with each module in the QAPI input. + """ + def __init__(self, env, qapidir): + self._env = env + self._qapidir = qapidir + + def visit_module(self, name): + if name is not None: + qapifile = self._qapidir + '/' + name + self._env.note_dependency(os.path.abspath(qapifile)) + super().visit_module(name) + + +class QAPIDocDirective(Directive): + """Extract documentation from the specified QAPI .json file""" + required_argument = 1 + optional_arguments = 1 + option_spec = { + 'qapifile': directives.unchanged_required + } + has_content = False + + def new_serialno(self): + """Return a unique new ID string suitable for use as a node's ID""" + env = self.state.document.settings.env + return 'qapidoc-%d' % env.new_serialno('qapidoc') + + def run(self): + env = self.state.document.settings.env + qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0] + qapidir = os.path.dirname(qapifile) + + try: + schema = QAPISchema(qapifile) + + # First tell Sphinx about all the schema files that the + # output documentation depends on (including 'qapifile' itself) + schema.visit(QAPISchemaGenDepVisitor(env, qapidir)) + + vis = QAPISchemaGenRSTVisitor(self) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + return vis.get_document_nodes() + except QAPIError as err: + # Launder QAPI parse errors into Sphinx extension errors + # so they are displayed nicely to the user + raise ExtensionError(str(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""" + app.add_config_value('qapidoc_srctree', None, 'env') + app.add_directive('qapi-doc', QAPIDocDirective) + + return dict( + version=__version__, + parallel_read_safe=True, + parallel_write_safe=True + ) diff --git a/MAINTAINERS b/MAINTAINERS index 5eed1e692b4..dbddb0a7635 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3149,6 +3149,7 @@ M: Peter Maydell S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/sphinx/ Miscellaneous ------------- From patchwork Fri Sep 25 16:23:03 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371442 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=YmyiWnKR; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycp3158Jz9sPB for ; Sat, 26 Sep 2020 02:30:03 +1000 (AEST) Received: from localhost ([::1]:54582 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqbh-0005Mr-2S for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:30:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47898) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVP-0006fp-PE for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:31 -0400 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]:43804) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVN-0006oP-Lk for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:31 -0400 Received: by mail-wr1-x432.google.com with SMTP id k15so4191862wrn.10 for ; Fri, 25 Sep 2020 09:23:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=qZjS93MWQ0G71t+DqqJoLIdR9lVhsNLA2fYrKCp5a3E=; b=YmyiWnKR67V/nnqTI08fBwyY2aG9QjvqdXg7LXwRIIMIns2Cnp612d5qsu9Ovqa3mD Kw114xiOI4fsYB8c3YmYJRHHflUEVOkIl63uaEMgC825icgZ7mSMlP7ZOLCXONzFHabJ 9rLXFelgiodzX/oqxwVIeS/JJ8g4VJO8G9uR7sO7MalOzAIyJ0EgpIYHQsqCqtCX5GBa SpalLXhZ5xHcCSLjMI3yx6QmOvrzY5xW6cepbtQVEN2JHaj0arfZBj7AFiiyVHfF5WOt xfdu8vOSrfo7oDZQhMckfB7CDHctmeuZthRbzsDs6QuencwJjzml6RyobtjfKJJXhP08 I/uA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=qZjS93MWQ0G71t+DqqJoLIdR9lVhsNLA2fYrKCp5a3E=; b=DZfW/FqAVAjXTgiP1reFcxi9uoesFD/uMrHGkwjchOfqFiWc0RE+rUgt8hB+h07ggL XB3JorjIEk5naI30PQVQcNse2jy2iMBlKsJy8MT6dpCQHgRXV8uZc4pr3SBgZTm5DQxr ZRdNX4QMIQq4sap1qauy+faoXmV6nLSs/4gYgeGxs64LI3WiJ9RaecnWkL7JHKjMXP/j L5bT4Zecg3eq4CvuZV+qKXrTogarLqcJN3PRgDypCETXqKGUeDB2giwNKjrajJjuDVlw 5wAdDJv/1QPuuxovafhTJrz9ZVURt7//iz2URE5iJCqce0lTOtKkIAbJ9EqhvWEKnhRr SkvA== X-Gm-Message-State: AOAM531Q7eH8YdTBf3j1bUHPRzKJMenT6PEYsuAqZ5QRg552PQn1bGH/ q/MPAB2Dr0tgu/wzpvMgnYuTnCo6+zrygSGL X-Google-Smtp-Source: ABdhPJyASieccQz0m+0M+R0adWTkBzmrtTRclnwAERRx3o5rszbE1Fi/rL5ALXfyMZbhFkF8kQwzig== X-Received: by 2002:a5d:4645:: with SMTP id j5mr4885072wrs.388.1601051007870; Fri, 25 Sep 2020 09:23:27 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:27 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 08/21] docs/interop: Convert qemu-ga-ref to rST Date: Fri, 25 Sep 2020 17:23:03 +0100 Message-Id: <20200925162316.21205-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::432; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x432.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Convert qemu-ga-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-ga-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. As the GA ref is now part of the Sphinx 'interop' manual, we can delete the direct link from index.html.in. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-ga-ref.rst | 9 ++++ docs/interop/qemu-ga-ref.texi | 80 ----------------------------------- docs/meson.build | 1 + meson.build | 3 -- MAINTAINERS | 2 +- qga/meson.build | 3 +- 9 files changed, 15 insertions(+), 87 deletions(-) create mode 100644 docs/interop/qemu-ga-ref.rst delete mode 100644 docs/interop/qemu-ga-ref.texi diff --git a/docs/index.html.in b/docs/index.html.in index ca28047881e..5b0f4e2bc2c 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -13,7 +13,6 @@
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
  • QMP Reference Manual
    • -
  • Guest Agent Protocol Reference
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index 42ce7e3d365..e83632e0108 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -19,4 +19,6 @@ html_theme_options['description'] = u'System Emulation Management and Interopera man_pages = [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', ['Michael Roth '], 8), + ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 006f9864208..738cdbe185e 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,6 +18,7 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-ga-ref vhost-user vhost-user-gpu vhost-vdpa diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst new file mode 100644 index 00000000000..669019de71d --- /dev/null +++ b/docs/interop/qemu-ga-ref.rst @@ -0,0 +1,9 @@ +QEMU Guest Agent Protocol Reference +=================================== + +.. + TODO: the old texinfo manual used to note that this manual + is GPL-v2-or-later. We should make that reader-visible + both here and in our Sphinx manuals more generally. + +.. qapi-doc:: qga/qapi-schema.json diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi deleted file mode 100644 index a23cc2ed7f6..00000000000 --- a/docs/interop/qemu-ga-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-ga-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU Guest Agent Protocol Reference - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU Guest Agent Protocol reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference -@end direntry - -@titlepage -@title Guest Agent Protocol Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU Guest Agent protocol reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qga/qga-qapi-doc.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye diff --git a/docs/meson.build b/docs/meson.build index 50f367349b8..2569dd52ad6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -15,6 +15,7 @@ if build_docs man_pages = { 'interop' : { 'qemu-ga.8': (have_tools ? 'man8' : ''), + 'qemu-ga-ref.7': 'man7', }, 'tools': { 'qemu-img.1': (have_tools ? 'man1' : ''), diff --git a/meson.build b/meson.build index f4d1ab10968..c01c6230b3f 100644 --- a/meson.build +++ b/meson.build @@ -1220,9 +1220,6 @@ if build_docs texi = { 'qemu-qmp-ref': ['docs/interop/qemu-qmp-ref.texi', qapi_doc_texi, version_texi], } - if 'CONFIG_GUEST_AGENT' in config_host - texi += {'qemu-ga-ref': ['docs/interop/qemu-ga-ref.texi', qga_qapi_doc_texi, version_texi]} - endif if makeinfo.found() cmd = [ diff --git a/MAINTAINERS b/MAINTAINERS index dbddb0a7635..4b2705fc143 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2418,9 +2418,9 @@ M: Michael Roth S: Maintained F: qga/ F: docs/interop/qemu-ga.rst +F: docs/interop/qemu-ga-ref.rst F: scripts/qemu-guest-agent/ F: tests/test-qga.c -F: docs/interop/qemu-ga-ref.texi T: git https://github.com/mdroth/qemu.git qga QOM diff --git a/qga/meson.build b/qga/meson.build index e5c5778a3e0..1c312b50cc9 100644 --- a/qga/meson.build +++ b/qga/meson.build @@ -16,7 +16,7 @@ qga_qapi_outputs = [ ] qga_qapi_files = custom_target('QGA QAPI files', - output: qga_qapi_outputs + ['qga-qapi-doc.texi'], + output: qga_qapi_outputs, input: 'qapi-schema.json', command: [ qapi_gen, '-o', 'qga', '-p', 'qga-', '@INPUT0@' ], depend_files: qapi_gen_depends) @@ -27,7 +27,6 @@ foreach output: qga_qapi_outputs qga_ss.add(qga_qapi_files[i]) i = i + 1 endforeach -qga_qapi_doc_texi = qga_qapi_files[i] qga_ss.add(files( 'commands.c', From patchwork Fri Sep 25 16:23:04 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371451 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=HhnsrxXf; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4BycxF0BmMz9ryj for ; Sat, 26 Sep 2020 02:36:17 +1000 (AEST) Received: from localhost ([::1]:43542 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqhi-0004Fx-UK for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:36:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47930) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVR-0006hC-9g for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:33 -0400 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]:46325) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVP-0006oZ-1M for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:33 -0400 Received: by mail-wr1-x42e.google.com with SMTP id o5so4176496wrn.13 for ; Fri, 25 Sep 2020 09:23:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=4wOYPsCKohpYAFpJ1D0YXxh8v2fqjVh385DsBoPjYbk=; b=HhnsrxXfb8kAGce+gXxNxiWebj9fEcOoQv8niZhJHUAdOkvEX0JaImOkLnuv3/bAb1 34aankHrhrkjjtbOWaxK5ySN33L/VwyCsa1QXu2CWNLdgJYL8wF4F73AoaxOrq5FnByh A3Lo/Xi/63R7m3CXKZBia+6C2JL2fvxtGk/POZRe/NtsMKljcMGyes6op3UbfVQrEXha KB1QeVEzfvjM/uqb5jYh9ZHk37H4/4qbud69cnKY51XVDUObtpxhh0C9XiQdTXFIosfJ fcxAAQhAmTOxDL0eQgCDycWuzZ4Fd46bLXgjy51HUHiHDqP5LkYspJcVoaIVGSh/PFX2 WYcA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=4wOYPsCKohpYAFpJ1D0YXxh8v2fqjVh385DsBoPjYbk=; b=FdZhhCcwdiAnlJJ8cfD1pcVVu2usu7kXnT2xKHz5IO8tYqHOiIqYaH2SiL8VbabzOu DrU4dwP2C803IxOOTqTH/p3zxgEvz+tFb6/z/OlF43LqJjlP+jzuw+2gI/vjkhNbMF0+ oNOSuJVU8/kQxB8/7f5V107nY68PgYzOWbz3cFx+WtVwEaEGOhBOWkalYACYl1dnV9gY hfM/Y41iL2vK0Ov1FlPeggRHqF5IfSclbOI+QRrbhu69/EHEqBjaPv83RkmaiS55Slmt PgzUP5t22PmKgxMikZ0SEzYBgRchjoQZ81nWvb0bahOveEcyvjPgcKzRp78uYWu0ZG12 pgng== X-Gm-Message-State: AOAM533ZlM/1WPUFehpm9bArt9roE6jgSk6iXIXagL3LIJRY/vcQoVI2 QchcDoSoK6K4Sie0lmzyRSClfBIthCcE1vqu X-Google-Smtp-Source: ABdhPJxvLbptwlYDVJGgWOVAqOj405aEg0mD8h7ubxeRQwFRSdqOGw9wow9mXKptCocf4dspdaOcCA== X-Received: by 2002:adf:df81:: with SMTP id z1mr5568781wrl.9.1601051009054; Fri, 25 Sep 2020 09:23:29 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:28 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 09/21] docs/interop: Convert qemu-qmp-ref to rST Date: Fri, 25 Sep 2020 17:23:04 +0100 Message-Id: <20200925162316.21205-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42e; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42e.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Convert qemu-qmp-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-qmp-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. Again, we drop the direct link from index.html.in now that the QMP ref is part of the interop manual. This commit removes the code from the root meson.build file that handled the various Texinfo-based outputs, because we no longer generate any documentation except for the Sphinx HTML manuals and the manpages, and the code can't handle having an empty list of files to process.. We'll do further cleanup of the remainders of Texinfo support in subsequent commits. Signed-off-by: Peter Maydell --- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-qmp-ref.rst | 9 ++++ docs/interop/qemu-qmp-ref.texi | 80 --------------------------------- docs/meson.build | 1 + meson.build | 82 ---------------------------------- qapi/meson.build | 4 +- 8 files changed, 14 insertions(+), 166 deletions(-) create mode 100644 docs/interop/qemu-qmp-ref.rst delete mode 100644 docs/interop/qemu-qmp-ref.texi diff --git a/docs/index.html.in b/docs/index.html.in index 5b0f4e2bc2c..33db4396ac8 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -12,7 +12,6 @@
  • Tools Guide
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
    • -
  • QMP Reference Manual
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index e83632e0108..43de386d33d 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -21,4 +21,6 @@ man_pages = [ ['Michael Roth '], 8), ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', [], 7), + ('qemu-qmp-ref', 'qemu-qmp-ref', u'QEMU QMP Reference Manual', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 738cdbe185e..cd78d679d82 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -19,6 +19,7 @@ Contents: pr-helper qemu-ga qemu-ga-ref + qemu-qmp-ref vhost-user vhost-user-gpu vhost-vdpa diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst new file mode 100644 index 00000000000..0c416fcaac2 --- /dev/null +++ b/docs/interop/qemu-qmp-ref.rst @@ -0,0 +1,9 @@ +QEMU QMP Reference Manual +========================= + +.. + TODO: the old texinfo manual used to note that this manual + is GPL-v2-or-later. We should make that reader-visible + both here and in our Sphinx manuals more generally. + +.. qapi-doc:: qapi/qapi-schema.json diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi deleted file mode 100644 index ea1d7fe6c2d..00000000000 --- a/docs/interop/qemu-qmp-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-qmp-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU QMP Reference Manual - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU QMP reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual -@end direntry - -@titlepage -@title QMP Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU QMP reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qapi/qapi-doc.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye diff --git a/docs/meson.build b/docs/meson.build index 2569dd52ad6..69097e2ca07 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -16,6 +16,7 @@ if build_docs 'interop' : { 'qemu-ga.8': (have_tools ? 'man8' : ''), 'qemu-ga-ref.7': 'man7', + 'qemu-qmp-ref.7': 'man7', }, 'tools': { 'qemu-img.1': (have_tools ? 'man1' : ''), diff --git a/meson.build b/meson.build index c01c6230b3f..73d675ca834 100644 --- a/meson.build +++ b/meson.build @@ -1203,88 +1203,6 @@ if 'CONFIG_GTK' in config_host subdir('po') endif -if build_docs - makeinfo = find_program('makeinfo', required: build_docs) - - docs_inc = [ - '-I', meson.current_source_dir(), - '-I', meson.current_build_dir() / 'docs', - '-I', '@OUTDIR@', - ] - - version_texi = configure_file(output: 'version.texi', - input: 'version.texi.in', - configuration: {'VERSION': meson.project_version(), - 'qemu_confdir': config_host['qemu_confdir']}) - - texi = { - 'qemu-qmp-ref': ['docs/interop/qemu-qmp-ref.texi', qapi_doc_texi, version_texi], - } - - if makeinfo.found() - cmd = [ - 'env', 'LC_ALL=C', makeinfo, '--no-split', '--number-sections', docs_inc, - '@INPUT0@', '-o', '@OUTPUT@', - ] - foreach ext, args: { - 'info': [], - 'html': ['--no-headers', '--html'], - 'txt': ['--no-headers', '--plaintext'], - } - t = [] - foreach doc, input: texi - output = doc + '.' + ext - t += custom_target(output, - input: input, - output: output, - install: true, - install_dir: qemu_docdir / 'interop', - command: cmd + args) - endforeach - alias_target(ext, t) - endforeach - endif - - texi2pdf = find_program('texi2pdf', required: false) - - if texi2pdf.found() - pdfs = [] - foreach doc, input: texi - output = doc + '.pdf' - pdfs += custom_target(output, - input: input, - output: output, - command: [texi2pdf, '-q', docs_inc, '@INPUT0@', '-o', '@OUTPUT@'], - build_by_default: false) - endforeach - alias_target('pdf', pdfs) - endif - - texi2pod = find_program('scripts/texi2pod.pl') - pod2man = find_program('pod2man', required: build_docs) - - if pod2man.found() - foreach doc, input: texi - man = doc + '.7' - pod = custom_target(man + '.pod', - input: input, - output: man + '.pod', - command: [texi2pod, - '-DVERSION="' + meson.project_version() + '"', - '-DCONFDIR="' + config_host['qemu_confdir'] + '"', - '@INPUT0@', '@OUTPUT@']) - man = custom_target(man, - input: pod, - output: man, - capture: true, - install: true, - install_dir: get_option('mandir') / 'man7', - command: [pod2man, '--utf8', '--section=7', '--center=" "', - '--release=" "', '@INPUT@']) - endforeach - endif -endif - if host_machine.system() == 'windows' nsis_cmd = [ find_program('scripts/nsis.py'), diff --git a/qapi/meson.build b/qapi/meson.build index 2b2872a41d8..a287ca5d9d7 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -97,7 +97,7 @@ foreach module : qapi_all_modules endforeach qapi_files = custom_target('shared QAPI source files', - output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs + ['qapi-doc.texi'], + output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs, input: [ files('qapi-schema.json') ], command: [ qapi_gen, '-o', 'qapi', '-b', '@INPUT0@' ], depend_files: [ qapi_inputs, qapi_gen_depends ]) @@ -121,5 +121,3 @@ foreach output : qapi_specific_outputs + qapi_nonmodule_outputs specific_ss.add(when: 'CONFIG_SOFTMMU', if_true: qapi_files[i]) i = i + 1 endforeach - -qapi_doc_texi = qapi_files[i] From patchwork Fri Sep 25 16:23:05 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371440 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=Oem/5z2S; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycn266gPz9ryj for ; Sat, 26 Sep 2020 02:29:10 +1000 (AEST) Received: from localhost ([::1]:51208 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqaq-0003zM-RA for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:29:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47940) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVR-0006hO-QI for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:33 -0400 Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]:50349) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVQ-0006of-2M for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:33 -0400 Received: by mail-wm1-x336.google.com with SMTP id e17so3637443wme.0 for ; Fri, 25 Sep 2020 09:23:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=6jDfZ800Wl3nx3KWVZmGyBEziqyPjN03/nUW4cQFzOE=; b=Oem/5z2SGcWKYvmOaHULvPMdjmAL+XrLoA+HQUw9GQVDzFrcLPxgi5FJrIDPFzUUCb OlpzxDqA3JEU+c9bhuxvTB/w3aEkpDLaRsqidW8TBjknKbHUY7Q9jb3udt2AmjhleTsm +nRzKo+bfLzB4j8Mv869/uKohgDx/ko4lPYC0jCNe/5Cwl0dMG7k+cfaAVJWyoubKZj3 G0NcU/pd2/uFnGcadaXxHBLlNZGIlpyyGKvmAE/lNpsaPWtT4aXhv5fuY0Fo7LE263// 6nzoJcSC1+iFePP28b5yAQW/90sLQsd7W2c/pQ6dJFXeQtRldoq5nPfKSx+qH1M0GE6Y ODgQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=6jDfZ800Wl3nx3KWVZmGyBEziqyPjN03/nUW4cQFzOE=; b=ql+g9PWzo3Q85axlv0zKQZMS0UrNeH/YLs0UrZ0Lt67jYWr9zFnGDBxhyfe4TPIgIF NrlAbwC9LxKaIo7Dqcgg7WNhRQIwadbd80ubNjbH0OTDqf/a0JxBy0UFMmawYN/AdI7G Nu4WFbb5InNPWdw/FkORZYBlrFLw8qM6EoXjsy0paheBhQp5VxDb2a65LRw5b+ueC9gW ZD5H+VhRNAwwdEynnWWZ2f4Uw4l3gd9YHDBOP/zN+/FbNu6M3JUXHcyV56cFiAK1cJLO 5+TdU7ppocDpYgl9ipCGExNPqRAfrvU1GMntA8VA6mpA1bRlz3pT8fczXUC08JBIpvoP 9WtQ== X-Gm-Message-State: AOAM531xr5U7D7AjHsOXiJZM5FI846s9zZVc/Wpfs06mByUrphe+pisU xsQa/r+SxZMjGAduP0DQlqSpK/XFyp6GnYcU X-Google-Smtp-Source: ABdhPJyU7qz9Cb4BVNMzPkQ50PH5uMTq6zv6xUzmiKgzda2qo5UxmiEInkwx20RM5ZcoXEIiBgrdtA== X-Received: by 2002:a1c:6a11:: with SMTP id f17mr3721924wmc.143.1601051010442; Fri, 25 Sep 2020 09:23:30 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:29 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 10/21] qapi: Use rST markup for literal blocks Date: Fri, 25 Sep 2020 17:23:05 +0100 Message-Id: <20200925162316.21205-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::336; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x336.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" There are exactly two places in our json doc comments where we use the markup accepted by the texi doc generator where a '|' in the first line of a doc comment means the line should be emitted as a literal block (fixed-width font, whitespace preserved). Since we use this syntax so rarely, instead of making the rST generator support it, instead just convert the two uses to rST-format literal blocks, which are indented and introduced with '::'. (The rST generator doesn't complain about the old style syntax, it just emits it with the '|' and with the whitespace not preserved, which looks odd, but means we can safely leave this change until after we've stopped generating texinfo.) Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- qapi/block-core.json | 16 +++++++++------- qapi/qapi-schema.json | 6 ++++-- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index dd77a91174c..86ed72ef9fa 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -570,13 +570,15 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# | 5| * -# | 4| * -# | 3| * * -# | 2| * * * -# | 1| * * * * -# | +------------------ -# | 10 50 100 +# :: +# +# 5| * +# 4| * +# 3| * * +# 2| * * * +# 1| * * * * +# +------------------ +# 10 50 100 # # Since: 4.0 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index f03ff91ceb5..6bafa81b727 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -21,8 +21,10 @@ # # Example: # -# | -> data issued by the Client -# | <- Server data response +# :: +# +# -> data issued by the Client +# <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. From patchwork Fri Sep 25 16:23:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371452 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=H1byI4t1; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycxb5tWKz9ryj for ; Sat, 26 Sep 2020 02:36:35 +1000 (AEST) Received: from localhost ([::1]:44242 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqi0-0004b7-P5 for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:36:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47952) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVS-0006iZ-IW for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:35 -0400 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:44093) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVR-0006ox-3L for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:34 -0400 Received: by mail-wr1-x442.google.com with SMTP id s12so4200861wrw.11 for ; Fri, 25 Sep 2020 09:23:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=BCWVGCPNXUFy3nRxMocemyad6VMwd8PqBpJd9BV4XTI=; b=H1byI4t15wSujl+40TPORXoUTeo5ZaWCkEdoKNVb/QRqsAoSP+UIH9jBRz+uUw6QGp 1G8praNbyptIMl854E58DW5duSe/54aktf9ec7GqhaSUtwWv1o1viJIVVe8/Fnf1YSsk ui8aIeKgaFRjbVZyBPb/N3CJtuPoKph2GyQDaGZkLl5Wd33ygKICAKG9v+apQjKqE+eL CF2yUzZSZqTYxJdTGY8plDx+ESbBBsNCwN86dNx72D+6zeFf5uzdltpKw40SS5Hzr3v0 3dUF7GcHjaSZG+6ejJphmmgEDk9fwW7guNmuEVCGSsrQhYH8ojRhePxbJZfwH5IIy0wv TzCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=BCWVGCPNXUFy3nRxMocemyad6VMwd8PqBpJd9BV4XTI=; b=pbG75FfRVl7yA7P/08SN3hvcQ5ppRDjNo7MCbPV8lWEajws1oMdPXJLughuCk9qn1M MKIPijxMkxV0Y7i9b9ZsqjXIw/yZnNCLpc3wqtKV1aWP4NLmFeRaQTfLAo1RVCnZmWhW 1da5LqP8TvQ1NS34fgrHImnnSPFCxtCTdvUBXGtCqBK+hJWJy5umjTaH8aZKfycylolf vEXa8MLxFg8l4672rNWsqkss54kkwvNSjr3MYBN/6ltDtwcTA7i2gSH/hYIV3mf2xt1k cMlZz8IdwA4OpkZiQAyrNv9gqCtG8vPeOje+HSc4RRiSfo9NbbjMQIYMafZ3Zq3sRBfg OBnw== X-Gm-Message-State: AOAM5325CwYkV6Kzj9iaGqlybxB8yKOuNQrK2RSo6XVFNM9Z1y379QPP isDu7ux76NYhRbLqbZW6HtUWnXSHmjhtfdK+ X-Google-Smtp-Source: ABdhPJyzuGNIm+v3roe/wNjaxp7HdxknkQAYJ77w7XoO9DHjC0bh+bhRUP7rM2LDTVSFU2TM5Gwk1w== X-Received: by 2002:a5d:60cc:: with SMTP id x12mr5320757wrt.84.1601051011557; Fri, 25 Sep 2020 09:23:31 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:30 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 11/21] qga/qapi-schema.json: Add some headings Date: Fri, 25 Sep 2020 17:23:06 +0100 Message-Id: <20200925162316.21205-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::442; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x442.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Add some section headings to the QGA json; this is purely so that we have some H1 headings, as otherwise each command ends up being visible in the interop/ manual's table of contents. In an ideal world there might be a proper 'Introduction' section the way there is in qapi/qapi-schema.json. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- qga/qapi-schema.json | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index d2ea7446db6..cec98c7e065 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,14 +2,16 @@ # vim: filetype=python ## -# -# General note concerning the use of guest agent interfaces: +# = General note concerning the use of guest agent interfaces # # "unsupported" is a higher-level error than the errors that individual # commands might document. The caller should always be prepared to receive # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't # document any failure mode at all. -# +## + +## +# = QEMU guest agent protocol commands and structs ## { 'pragma': { 'doc-required': true } } From patchwork Fri Sep 25 16:23:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371450 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=ILhYsBqm; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4BycxC4YBGz9ryj for ; Sat, 26 Sep 2020 02:36:15 +1000 (AEST) Received: from localhost ([::1]:43446 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqhh-0004DM-3o for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:36:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47968) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVT-0006ja-Tb for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:36 -0400 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:36391) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVS-0006pJ-8t for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:35 -0400 Received: by mail-wr1-x441.google.com with SMTP id z1so4249287wrt.3 for ; Fri, 25 Sep 2020 09:23:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=2fo9KhPCNYW+F0sc33/RwPCGaMMzyxHJl2mjQCHcWVQ=; b=ILhYsBqm/G3LakPho1BoLo9PHmXUYJUJBYE5V0pHW3b7W/Rb56wkyFLqjKsLF2GjJt oE/UFSqvdVbwCuDhSDzdWidtPWR+CZOY84TAM+js+LOItPPgIvw/SWU8KRnGsjyc8px9 uhYgtAn6ObsG5SQl960Yssa9cCUKGG42N1ejJHXubtErLhCUsEf0ivvkBYbvjuX8rZ5l Wklg8xRVkGql/x8gQPPBBQC6oDH9kWYFI4S5uwLLHRcbNxzbkkl+bnmAtPKM1HlLLDBo Ra7yTo5QuYKRINhYR+yh/etqUG0TXURd2clU6PSbYwT5BIRbg9K5BH2366Kb7Bm2ie1q /RGw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=2fo9KhPCNYW+F0sc33/RwPCGaMMzyxHJl2mjQCHcWVQ=; b=iKm8xa3S/9yupv2sudNQKuUoITEgLtSBTlEmfHRrOOx39JMEyqu6ZOpNSwqADr3qx4 A/WEqCSMnl51ATArBUjuL+r1JSztqlb+7dSkCcgt+OwvR/rV60bK3j8LqhLWQbSBOJ6T /MK3A0n0hoKzPOXirSOfD14nWh0CLFF3UC0nffWGbJ1R+cwngGfw8AF65PurAI5/MUpo q+M6mMRvBXZxnCOsWAeuMziZCtKXwrJ0xOGDFDFStB6ZmS0sbrPmE/QRQN/l+FIskF/j b6GFNWVxYzyEmBWY4bct9SCwn4JF02EbC+eJT9bG38t5iXwKUCkVZnCY24p+G+rCqNMU YBYQ== X-Gm-Message-State: AOAM532+KqoXoERtvyZESylS0AskmSAffhyMcvj83ksJIKBpTnvJJcxX nb7Mfuk1dOiwjVTT/BWSWHhH9CDl+rSV3nV6 X-Google-Smtp-Source: ABdhPJymVcifPlwdaXncrMZQk3zFji1MGfBUxOHM34fO6zeF+X0bGouwxhS9Adgq2+0ThsGhzsJjiA== X-Received: by 2002:adf:e304:: with SMTP id b4mr5155282wrj.141.1601051012628; Fri, 25 Sep 2020 09:23:32 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:32 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 12/21] tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis Date: Fri, 25 Sep 2020 17:23:07 +0100 Message-Id: <20200925162316.21205-13-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::441; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x441.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" doc-good.json currently uses the old *strong* and _emphasis_ markup. As part of the conversion to rST this needs to switch to **strong** and *emphasis*, because rST uses underscores as part of its markup of hyperlinks and will otherwise warn about the syntax error. In commit a660eed482063b we fixed up the in-tree uses of the old markup: 1) _this_ was replaced with *this* 2) the only in-tree use of *this* was left alone (turning a 'strong' into an 'emphasis') (and so currently in-tree nothing is using either new-style **strong** or old-style _emphasis_). Update doc-good.json in a similar way: 1) replace _this_ with *this* 2) remove the usage of old-style *this* (This slightly reduces the coverage for the old Texinfo generator, which is about to go away, but is fine for the new rST generator because that does not need to handle strong/emphasis itself because it is simply passing the entire text as raw rST to Sphinx.) Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- tests/qapi-schema/doc-good.json | 2 +- tests/qapi-schema/doc-good.out | 2 +- tests/qapi-schema/doc-good.texi | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index c6822145c49..e9af0857db7 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -10,7 +10,7 @@ # # == Subsection # -# *strong* _with emphasis_ +# *with emphasis* # @var {in braces} # # * List item one diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index b7e3f4313da..419284dae29 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -73,7 +73,7 @@ doc freeform body= == Subsection -*strong* _with emphasis_ +*with emphasis* @var {in braces} * List item one diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index 12808989ffb..29abef33e98 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -4,7 +4,7 @@ @subsection Subsection -@strong{strong} @emph{with emphasis} +@strong{with emphasis} @code{var} @{in braces@} @itemize @bullet From patchwork Fri Sep 25 16:23:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371456 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=aoFRQTk8; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd173MvXz9ryj for ; Sat, 26 Sep 2020 02:39:39 +1000 (AEST) Received: from localhost ([::1]:52572 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqkz-0008Jz-90 for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:39:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:47982) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVV-0006kO-Am for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:37 -0400 Received: from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b]:34299) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVT-0006pZ-FQ for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:37 -0400 Received: by mail-wr1-x42b.google.com with SMTP id t10so4270846wrv.1 for ; Fri, 25 Sep 2020 09:23:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=FBXPGy4Klp9jR272eFs+vFXX4JatTC9w4gnl2L3wGwM=; b=aoFRQTk8aCC3CHzz0MKU/jnPXCmTb8bzpkTpPXd+TvFw3NfehyZi6fOH1f+Fxwvkk4 dNCx8BEuf601p05FQMPvGD7OZx1fWaoBrdCxgsE80tSu6yyFN83anJeVNz8hwUKJjp1R ejN+/kd7rG90qE4p8PtwREKV2otmIX4i9BlwTo4Pbfkdw1OYCnebXlJSNcyAjKsaDT8U oNIirMulqWpHYSRXjDznDpvzg22JT0AFsDQIXdvGCtFKFLvg/ZAsxZ9TYh8US/ExMKJv T/z6N1kef+urrraW1mbQOaVxFbwnMAIwOmbQ+oDsFxyHBZvkwvslXzXO+HzRb2dRUp+w 8VmA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=FBXPGy4Klp9jR272eFs+vFXX4JatTC9w4gnl2L3wGwM=; b=lUBdEYlEGKpOfm6N8AjtRjESWgesj1eiX+XZDD14EL3Iaz7ypd6xZ4dPZAzNSYWktl yMCB1vmTJr/4N3RGwj3dOj+lSqmUE+r2TLbr69DxEDm+2/JKND5wf6Bad9W1Epz4xVLY wSqp2KD4yYOt2h6nHzy8oE2G2cbmuh/bxQ19/IfPIEoYf1XkSe+NgaIM4AVVFQp3Y1R0 zz1cygy7JPlvvNOKG1FgRzzbkG4g5eTxIHcDiNBX4nINYr7M/imxbVEmW3PYJCJV/qnK vxnAOzGiZ0Ffec0H95AKn8geVrAQySgr0Pzh6DkEMii9MWHcDTeIZ4bZexBwCxIvxAMV ROTg== X-Gm-Message-State: AOAM532SZYYZPqSmlFYOM8+5KtCPgkqgxz7GJ4Rea6ArAIAKXvmJLyiL 1you0nlbJ8wWYq7YDcrVTSPxNa9jLjIJ4lmX X-Google-Smtp-Source: ABdhPJztB7Nfdn+wqkAa4jjRlgpJGNfZ647xrloJJWdmyWDZEbmnaL5/KvLHNMtTfGGGwAvHIYfBDw== X-Received: by 2002:adf:8b1d:: with SMTP id n29mr5156184wra.383.1601051013686; Fri, 25 Sep 2020 09:23:33 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:33 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 13/21] meson.build: Move SPHINX_ARGS to top level meson.build file Date: Fri, 25 Sep 2020 17:23:08 +0100 Message-Id: <20200925162316.21205-14-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42b; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42b.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We're going to want to use SPHINX_ARGS in both docs/meson.build and tests/qapi-schema/meson.build. Move the definition up to the top level file so it is available to both subdirectories. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- docs/meson.build | 8 -------- meson.build | 8 ++++++++ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/meson.build b/docs/meson.build index 69097e2ca07..99da609e813 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,11 +1,3 @@ -SPHINX_ARGS = [config_host['SPHINX_BUILD'], - '-Dversion=' + meson.project_version(), - '-Drelease=' + config_host['PKGVERSION']] - -if get_option('werror') - SPHINX_ARGS += [ '-W' ] -endif - if build_docs configure_file(output: 'index.html', input: files('index.html.in'), diff --git a/meson.build b/meson.build index 73d675ca834..6408ad442ea 100644 --- a/meson.build +++ b/meson.build @@ -671,6 +671,14 @@ foreach d : hx_headers endforeach genh += hxdep +SPHINX_ARGS = [config_host['SPHINX_BUILD'], + '-Dversion=' + meson.project_version(), + '-Drelease=' + config_host['PKGVERSION']] + +if get_option('werror') + SPHINX_ARGS += [ '-W' ] +endif + # Collect sourcesets. util_ss = ss.source_set() From patchwork Fri Sep 25 16:23:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371462 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=Dwo1VRN0; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd4p62N8z9sR4 for ; Sat, 26 Sep 2020 02:42:50 +1000 (AEST) Received: from localhost ([::1]:60776 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqo4-0003aC-1d for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:42:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48000) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVX-0006nS-NC for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:41 -0400 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:45582) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVV-0006pl-0J for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:39 -0400 Received: by mail-wr1-x435.google.com with SMTP id x14so4188404wrl.12 for ; Fri, 25 Sep 2020 09:23:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=qY2/0F+KpB2LvKmpEVYN1JeJz0DmkWbUEhi/m2WaAQM=; b=Dwo1VRN0HctI0eR9SiDm2YZDriqLyQF2ran5BiImW24LJO041VlhJ1zI+v4cNMgWK7 RjQGjklZVPSOqt+VCQmUZw5L+ptGJ1tm4x6Vn6oUFILVGzlECBrBDamdm91Sy06rZfXa qRLIunzB/WtK7/qrO893ZEAcnk8fyE9/n3MNJisEr8sJyWF8Pwyb2roXKiaT7vyoc44A 1aei1uKsuCUDy4PvnCf0Tqx8N5kxeOGg7n+xoHdOZmv6sSzoGjKjlf1Dqa9sxIt7LsyL pyc9fFxTQNhSp5CvcU9vgvJgdx5uKpDm8j3nQw0Pz8OBLTNmfulbNZVD5xvcWnqc9xJH UHlA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=qY2/0F+KpB2LvKmpEVYN1JeJz0DmkWbUEhi/m2WaAQM=; b=d9U/RGHcxKvdzvbkKgwR9E0hpvm2P8hgfZmQHy8+b9DU1XMKRmS3Zvk/4GI3AsX1Rs 3vJCToSJTRZMQIfQ1tjwyVzbRgVoWyDqJcqWVex34o8RjWw5blYRcl7tOmsQ0LwQSPyx 1uboD/vXpV2cyJn5fqCy87/XMBRyULeiOy7e7EcUejsgleXrcAfEfa9VStJ8CoPOhpVq 0f3NJemVTWyAx1HXs8j0Em5WcYShUjMnZX5mCan7HtUDv1c7y/GRnFhWQykmgIWnYicM nYSEQGm3d07ps5IEdb4WkJ2AVCsElKwv9a/aRBi+5lk8PzYrAN8+KksgGIZT8gYCKNUn Tu5Q== X-Gm-Message-State: AOAM530SV7R0QAy4tfVJpILn8TQBUYR0gBVFSczYEkBbY8pL9pfcWcCp i2q0mm0o9dZ4EKlI39Misk38S210nqTnOqvc X-Google-Smtp-Source: ABdhPJyAnE4IwgMDhnsRUPyvmYxviC0kY/TzRJG97OEH60uNh11++Dx42rfrFocTeYgPA/b/nAzUxw== X-Received: by 2002:adf:8162:: with SMTP id 89mr5551556wrm.237.1601051014991; Fri, 25 Sep 2020 09:23:34 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:34 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 14/21] meson.build: Make manuals depend on source to Sphinx extensions Date: Fri, 25 Sep 2020 17:23:09 +0100 Message-Id: <20200925162316.21205-15-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::435; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x435.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" The automatic dependency handling for Sphinx manuals only makes the output depend on the input documentation files. This means that if you edit the Python source of an extension then the documentation won't be rebuilt. Create a list of all the source files for the extensions and add it to the dependencies for the manuals. This is similar to how we handle the qapi_gen_depends list. Because we don't try to identify which manuals are using which Sphinx extensions, a change to the source of one extension will always rebuild the entire manual set, not merely the manuals which have changed. This is acceptable because we don't change the extensions all that often. Signed-off-by: Peter Maydell --- docs/meson.build | 1 + meson.build | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/docs/meson.build b/docs/meson.build index 99da609e813..59fea873b10 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -36,6 +36,7 @@ if build_docs output: [manual + '.stamp'], input: [files('conf.py'), files(manual / 'conf.py')], depfile: manual + '.d', + depend_files: sphinx_extn_depends, command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@', '-Ddepfile_stamp=@OUTPUT0@', '-b', 'html', '-d', private_dir, diff --git a/meson.build b/meson.build index 6408ad442ea..3c07e75dbd5 100644 --- a/meson.build +++ b/meson.build @@ -679,6 +679,14 @@ if get_option('werror') SPHINX_ARGS += [ '-W' ] endif +sphinx_extn_depends = [ meson.source_root() / 'docs/sphinx/depfile.py', + meson.source_root() / 'docs/sphinx/hxtool.py', + meson.source_root() / 'docs/sphinx/kerneldoc.py', + meson.source_root() / 'docs/sphinx/kernellog.py', + meson.source_root() / 'docs/sphinx/qapidoc.py', + meson.source_root() / 'docs/sphinx/qmp_lexer.py', + qapi_gen_depends ] + # Collect sourcesets. util_ss = ss.source_set() From patchwork Fri Sep 25 16:23:10 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371454 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=qA9JkOcC; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd0n2TSlz9sR4 for ; Sat, 26 Sep 2020 02:39:21 +1000 (AEST) Received: from localhost ([::1]:51896 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqkh-00080s-9k for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:39:19 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48022) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVa-0006no-0h for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:43 -0400 Received: from mail-wm1-x32c.google.com ([2a00:1450:4864:20::32c]:38458) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVX-0006px-BR for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:41 -0400 Received: by mail-wm1-x32c.google.com with SMTP id v12so3932482wmh.3 for ; Fri, 25 Sep 2020 09:23:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=KVVuW3PO55zfdvToP+0jRG2qg+98RNhIlL0hnILKI6I=; b=qA9JkOcCC6Gq25FojZ6HoRs9QvsrqA8jpoSWBhFIJnpgedjyTd3FLPlsQZtGElwocQ u4EVy/n5NbRf3B6VV9r18N5uI0DMa4HYV3SKMSLhRUZKcGPDK+3+l7WPtWtQkuSY1wF0 LScE6QlmKxzxqAFaVh27Ey+emGQTs8mNTCjYwLP9p3t3qZmrYN9pjEREqv78jnbwTt3v +3FCdNXJXUU9MO8mHq7SaIjEUfGVKwNXbHEFINDHdMnMC45bbIbcB8HoMUkRTgBLn/mi prBIDwi5VGviah/MJ1rcxRm3O6HfrEMHiEKrj8v6RWzoDBMQhMnwbNkhEVUYAJyiTpdr QB3w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=KVVuW3PO55zfdvToP+0jRG2qg+98RNhIlL0hnILKI6I=; b=C0lrOWvHtDdOSGKHgaTCf2Qms2VqdxaA3x3Y19sYPLzG1O5jiLhtAOZZSImzkPTGxZ 6vbd9Z91L2FI6zgJBozc8Nl+v3auAEeMuftFb3h261yvZT4o9X9bWmQFfqAlEe+zGmYd uB9ztiTYozgE6lj29/Musqo0KW+Ql1QCGulG2PAMm+14m/sF4tLRG72oF+7TigN83bVL ELeNRX8MPfWoRugWb5MJ4n29mDvJmvwi2o/ZCY99PxtnRU3eik8eVwClXpdvZh1n/hKo JdfotttuKX/44rzuQGipGQcN5gA6Fi8Ly7BY/cGaCEtkDv8Pz6KkkSqoFsmboZxQuRA9 VppQ== X-Gm-Message-State: AOAM531Zr5kC9MQmYtT+gWasshXQUZ1JTwAFP33tYnv9GQdI4V5jp2HK 8VZPhXtPFqCbN8Rhy92/z8Ym2DfeI9MYakiF X-Google-Smtp-Source: ABdhPJy4zgNme3wSMP2iF40f1MpkUDOpwN/zgVFjbSiXqPNytebTK07qPxzOxdCY+j1zTgPyN44TDQ== X-Received: by 2002:a1c:e1d6:: with SMTP id y205mr3978841wmg.92.1601051016312; Fri, 25 Sep 2020 09:23:36 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:35 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 15/21] tests/qapi-schema: Add test of the rST QAPI doc-comment outputn Date: Fri, 25 Sep 2020 17:23:10 +0100 Message-Id: <20200925162316.21205-16-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32c; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32c.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, WEIRD_QUOTING=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Add a test of the rST output from the QAPI doc-comment generator, similar to what we currently have that tests the Texinfo output. This is a bit more awkward with Sphinx, because the generated output is not 100% under our control the way the QAPI-to-Texinfo generator was. However, in practice Sphinx's plaintext output generation has been identical between at least Sphinx 1.6 and 3.0, so we use that. (The HTML output has had changes across versions). We use an exact-match comparison check, with the understanding that perhaps changes in a future Sphinx version might require us to implement something more clever to cope with variation in the output. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- The meson.build changes are remarkably clunky, but this appears to be unavoidable... --- tests/qapi-schema/doc-good.rst | 5 + tests/qapi-schema/doc-good.txt | 288 +++++++++++++++++++++++++++++++++ tests/qapi-schema/meson.build | 55 +++++++ 3 files changed, 348 insertions(+) create mode 100644 tests/qapi-schema/doc-good.rst create mode 100644 tests/qapi-schema/doc-good.txt diff --git a/tests/qapi-schema/doc-good.rst b/tests/qapi-schema/doc-good.rst new file mode 100644 index 00000000000..1e4c23305a1 --- /dev/null +++ b/tests/qapi-schema/doc-good.rst @@ -0,0 +1,5 @@ +.. + Test Sphinx manual that pulls in the test schema file. We will generate + a plain-text output file and compare it against a reference. + +.. qapi-doc:: tests/qapi-schema/doc-good.json diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt new file mode 100644 index 00000000000..6ca03d49d0d --- /dev/null +++ b/tests/qapi-schema/doc-good.txt @@ -0,0 +1,288 @@ +Section +******* + + +Subsection +========== + +*with emphasis* "var" {in braces} + +* List item one + +* Two, multiple lines + +* Three Still in list + +Not in list + +* Second list Note: still in list + +Note: not in list + +1. Third list is numbered + +2. another item + +Returns: the King Since: the first age Notes: + +1. Lorem ipsum dolor sit amet + +2. Ut enim ad minim veniam + +Duis aute irure dolor + +Example: + +-> in <- out Examples: - *verbatim* - {braces} + + +"Enum" (Enum) +------------- + + +Values +~~~~~~ + +"one" (**If: **"defined(IFONE)") + The _one_ {and only} + +"two" + Not documented + + +Features +~~~~~~~~ + +"enum-feat" + Also _one_ {and only} + +"two" is undocumented + + +If +~~ + +"defined(IFCOND)" + + +"Base" (Object) +--------------- + + +Members +~~~~~~~ + +"base1": "Enum" + the first member + + +"Variant1" (Object) +------------------- + +A paragraph + +Another paragraph (but no "var": line) + + +Members +~~~~~~~ + +"var1": "string" (**If: **"defined(IFSTR)") + Not documented + + +Features +~~~~~~~~ + +"variant1-feat" + a feature + +"member-feat" + a member feature + + +"Variant2" (Object) +------------------- + + +"Object" (Object) +----------------- + + +Members +~~~~~~~ + +The members of "Base" +The members of "Variant1" when "base1" is ""one"" +The members of "Variant2" when "base1" is ""two"" (**If: **"IFTWO") + +Features +~~~~~~~~ + +"union-feat1" + a feature + + +"SugaredUnion" (Object) +----------------------- + + +Members +~~~~~~~ + +"type" + One of "one", "two" + +"data": "Variant1" when "type" is ""one"" +"data": "Variant2" when "type" is ""two"" (**If: **"IFTWO") + +Features +~~~~~~~~ + +"union-feat2" + a feature + + +"Alternate" (Alternate) +----------------------- + + +Members +~~~~~~~ + +"i": "int" + an integer "b" is undocumented + +"b": "boolean" + Not documented + + +Features +~~~~~~~~ + +"alt-feat" + a feature + + +Another subsection +================== + + +"cmd" (Command) +--------------- + + +Arguments +~~~~~~~~~ + +"arg1": "int" + the first argument + +"arg2": "string" (optional) + the second argument + +"arg3": "boolean" + Not documented + + +Features +~~~~~~~~ + +"cmd-feat1" + a feature + +"cmd-feat2" + another feature + + +Note +~~~~ + +"arg3" is undocumented + + +Returns +~~~~~~~ + +"Object" + + +TODO +~~~~ + +frobnicate + + +Notes +~~~~~ + +* Lorem ipsum dolor sit amet + +* Ut enim ad minim veniam + +Duis aute irure dolor + + +Example +~~~~~~~ + + -> in + <- out + + +Examples +~~~~~~~~ + + - *verbatim* + - {braces} + + +Since +~~~~~ + +2.10 + + +"cmd-boxed" (Command) +--------------------- + +If you're bored enough to read this, go see a video of boxed cats + + +Arguments +~~~~~~~~~ + +The members of "Object" + +Features +~~~~~~~~ + +"cmd-feat1" + a feature + +"cmd-feat2" + another feature + + +Example +~~~~~~~ + + -> in + + <- out + + +"EVT-BOXED" (Event) +------------------- + + +Arguments +~~~~~~~~~ + +The members of "Object" + +Features +~~~~~~~~ + +"feat3" + a feature diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 83a0a68389b..0c4a6a2936f 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -224,3 +224,58 @@ qapi_doc = custom_target('QAPI doc', test('QAPI doc', diff, args: ['-b', '-u', files('doc-good.texi'), qapi_doc[0].full_path()], depends: qapi_doc, suite: ['qapi-schema', 'qapi-doc']) + +# Test the document-comment document generation code by running a test schema +# file through Sphinx's plain-text builder and comparing the result against +# a golden reference. This is in theory susceptible to failures if Sphinx +# changes its output, but the text output has historically been very stable +# (no changes between Sphinx 1.6 and 3.0), so it is a better bet than +# texinfo or HTML generation, both of which have had changes. We might +# need to add more sophisticated logic here in future for some sort of +# fuzzy comparison if future Sphinx versions produce different text, +# but for now the simple comparison suffices. +qapi_doc_out = custom_target('QAPI rST doc', + output: ['doc-good.txt'], + input: files('doc-good.json', 'doc-good.rst'), + build_by_default: build_docs, + depend_files: sphinx_extn_depends, + # We use -E to suppress Sphinx's caching, because + # we want it to always really run the QAPI doc + # generation code. It also means we don't + # clutter up the build dir with the cache. + command: [SPHINX_ARGS, + '-b', 'text', '-E', + '-c', meson.source_root() / 'docs', + '-D', 'master_doc=doc-good', + meson.current_source_dir(), + meson.current_build_dir()]) + +# Fix possible inconsistency in line endings in generated output and +# in the golden reference (which could otherwise cause test failures +# on Windows hosts). Unfortunately diff --strip-trailing-cr +# is GNU-diff only. The odd-looking perl is because we must avoid +# using an explicit '\' character in the command arguments to +# a custom_target(), as Meson will unhelpfully replace it with a '/' +# (https://github.com/mesonbuild/meson/issues/1564) +qapi_doc_out_nocr = custom_target('QAPI rST doc newline-sanitized', + output: ['doc-good.txt.nocr'], + input: qapi_doc_out[0], + build_by_default: build_docs, + command: ['perl', '-pe', '$x = chr 13; s/$x$//', '@INPUT@'], + capture: true) + +qapi_doc_ref_nocr = custom_target('QAPI rST doc reference newline-sanitized', + output: ['doc-good.ref.nocr'], + input: files('doc-good.txt'), + build_by_default: build_docs, + command: ['perl', '-pe', '$x = chr 13; s/$x$//', '@INPUT@'], + capture: true) + +if build_docs + # "full_path()" needed here to work around + # https://github.com/mesonbuild/meson/issues/7585 + test('QAPI rST doc', diff, args: ['-u', qapi_doc_ref_nocr[0].full_path(), + qapi_doc_out_nocr[0].full_path()], + depends: [qapi_doc_ref_nocr, qapi_doc_out_nocr], + suite: ['qapi-schema', 'qapi-doc']) +endif From patchwork Fri Sep 25 16:23:11 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371460 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=TnDQFvfe; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd471Y1kz9sSn for ; Sat, 26 Sep 2020 02:42:13 +1000 (AEST) Received: from localhost ([::1]:60214 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqnT-0003Kw-0u for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:42:11 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48072) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVd-0006oF-W3 for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:47 -0400 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:37677) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVZ-0006qO-NO for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:45 -0400 Received: by mail-wm1-x344.google.com with SMTP id a9so3950468wmm.2 for ; Fri, 25 Sep 2020 09:23:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=47EEZbmQdkYpH2g6SRnaUxS9mqqkJXBkDoApjoPRy+A=; b=TnDQFvfeTfNO30lF1pdyJIIGzrx8JRbxBNrP1wqwhyBEZGEbAFtrPxpiinT+APLwmB N15UgXmLWaZVylr2mIEU6lPRzyayg9wSiXmWICOvnSDwYy8SETIAzIlAQwOjysAWjS9l 6bCADy4ef5HfC2/JT8YrLdjCuoaB2VkXGUpv/6Ff0uX/l4C42Gff2BwRzNO+MlcgyvV6 orzCXko5ymtYypHcLpwwIzTfQ+W707eGg5RpBjEPDJzhnhVavjEBCIJy+EvRq265s7KT 5cQrPkEPlRYALvLJhOws+qmkjyt3YZIL+ecAcEyMvDdonO0HmlLMm9OES0BgDfCH2Ggx GQ6Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=47EEZbmQdkYpH2g6SRnaUxS9mqqkJXBkDoApjoPRy+A=; b=CFO9CKxzscY47ww7aq8JBV5SULsFO9JvkZCNenGbt7d8Sf8nb269L7q1ioX/H2+GsF M8Iseheuc8V2JiKLa80dN289GI8SoRfY3ubAgQ1WORfAAh5RlVgTIFrdNBCL+Lc5MnAQ 4YhigPoUggquifnYJWp22mA1LvDyKzpVBmpuRXkI4+UFw8tjJOz9wjkfHOVLH+3FHz4O 3l0Lbc/+vDUpxOazGGoSq5FJLlcTAfzeS6ZlUf0y56KZNVEl5qIFBIf4aAAJ/xHQWCbw BPkeVmEFBRcFn4UGAipkXjr82bJFLFTjf7sLY80sxBdYou3XlBithyzD8a0PLqI2novO B59w== X-Gm-Message-State: AOAM532RG7FivZBl/s2nW+3+KokCRYWHh/5ob6fMqsy0PnYH0yZfKfOj VcU8eoqwnxOG4Pe7NBMqdrEOmT9S7rMR0UpC X-Google-Smtp-Source: ABdhPJwiQ/6Ar1PoAKI3HhC9BsOFeIbM9uk/LvMdFQv4zv2thglhis1YSw3fb9EqlsQiOPhxjLNg8A== X-Received: by 2002:a1c:9c13:: with SMTP id f19mr3786643wme.97.1601051017710; Fri, 25 Sep 2020 09:23:37 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:37 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 16/21] scripts/qapi: Remove texinfo generation support Date: Fri, 25 Sep 2020 17:23:11 +0100 Message-Id: <20200925162316.21205-17-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::344; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x344.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We no longer use the generated texinfo format documentation, so delete the code that generates it, and the test case for the generation. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- meson.build | 2 - scripts/qapi-gen.py | 2 - scripts/qapi/doc.py | 302 ------------------------------ scripts/qapi/gen.py | 7 - tests/qapi-schema/doc-good.texi | 313 -------------------------------- tests/qapi-schema/meson.build | 9 +- 6 files changed, 1 insertion(+), 634 deletions(-) delete mode 100644 scripts/qapi/doc.py delete mode 100644 tests/qapi-schema/doc-good.texi diff --git a/meson.build b/meson.build index 3c07e75dbd5..339149759c7 100644 --- a/meson.build +++ b/meson.build @@ -618,7 +618,6 @@ qapi_gen = find_program('scripts/qapi-gen.py') qapi_gen_depends = [ meson.source_root() / 'scripts/qapi/__init__.py', meson.source_root() / 'scripts/qapi/commands.py', meson.source_root() / 'scripts/qapi/common.py', - meson.source_root() / 'scripts/qapi/doc.py', meson.source_root() / 'scripts/qapi/error.py', meson.source_root() / 'scripts/qapi/events.py', meson.source_root() / 'scripts/qapi/expr.py', @@ -630,7 +629,6 @@ qapi_gen_depends = [ meson.source_root() / 'scripts/qapi/__init__.py', meson.source_root() / 'scripts/qapi/types.py', meson.source_root() / 'scripts/qapi/visit.py', meson.source_root() / 'scripts/qapi/common.py', - meson.source_root() / 'scripts/qapi/doc.py', meson.source_root() / 'scripts/qapi-gen.py' ] diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py index 4b03f7d53be..541e8c1f55d 100644 --- a/scripts/qapi-gen.py +++ b/scripts/qapi-gen.py @@ -10,7 +10,6 @@ import re import sys from qapi.commands import gen_commands -from qapi.doc import gen_doc from qapi.events import gen_events from qapi.introspect import gen_introspect from qapi.schema import QAPIError, QAPISchema @@ -51,7 +50,6 @@ def main(argv): gen_commands(schema, args.output_dir, args.prefix) gen_events(schema, args.output_dir, args.prefix) gen_introspect(schema, args.output_dir, args.prefix, args.unmask) - gen_doc(schema, args.output_dir, args.prefix) if __name__ == '__main__': diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py deleted file mode 100644 index 7764de1e4bc..00000000000 --- a/scripts/qapi/doc.py +++ /dev/null @@ -1,302 +0,0 @@ -# QAPI texi generator -# -# This work is licensed under the terms of the GNU LGPL, version 2+. -# See the COPYING file in the top-level directory. -"""This script produces the documentation of a qapi schema in texinfo format""" - -import re -from qapi.gen import QAPIGenDoc, QAPISchemaVisitor - - -MSG_FMT = """ -@deftypefn {type} {{}} {name} - -{body}{members}{features}{sections} -@end deftypefn - -""".format - -TYPE_FMT = """ -@deftp {{{type}}} {name} - -{body}{members}{features}{sections} -@end deftp - -""".format - -EXAMPLE_FMT = """@example -{code} -@end example -""".format - - -def subst_strong(doc): - """Replaces *foo* by @strong{foo}""" - return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) - - -def subst_emph(doc): - """Replaces _foo_ by @emph{foo}""" - return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) - - -def subst_vars(doc): - """Replaces @var by @code{var}""" - return re.sub(r'@([\w-]+)', r'@code{\1}', doc) - - -def subst_braces(doc): - """Replaces {} with @{ @}""" - return doc.replace('{', '@{').replace('}', '@}') - - -def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, we - # need to delay it until after subst_vars() in texi_format(). - doc = subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=doc) - - -def texi_format(doc): - """ - Format documentation - - Lines starting with: - - |: generates an @example - - =: generates @section - - ==: generates @subsection - - 1. or 1): generates an @enumerate @item - - */-: generates an @itemize list - """ - ret = '' - doc = subst_braces(doc) - doc = subst_vars(doc) - doc = subst_emph(doc) - doc = subst_strong(doc) - inlist = '' - lastempty = False - for line in doc.split('\n'): - line = line.strip() - empty = line == '' - - # FIXME: Doing this in a single if / elif chain is - # problematic. For instance, a line without markup terminates - # a list if it follows a blank line (reaches the final elif), - # but a line with some *other* markup, such as a = title - # doesn't. - # - # Make sure to update section "Documentation markup" in - # docs/devel/qapi-code-gen.txt when fixing this. - if line.startswith('| '): - line = EXAMPLE_FMT(code=line[2:]) - elif line.startswith('= '): - line = '@section ' + line[2:] - elif line.startswith('== '): - line = '@subsection ' + line[3:] - elif re.match(r'^([0-9]*\.) ', line): - if not inlist: - ret += '@enumerate\n' - inlist = 'enumerate' - ret += '@item\n' - line = line[line.find(' ')+1:] - elif re.match(r'^[*-] ', line): - if not inlist: - ret += '@itemize %s\n' % {'*': '@bullet', - '-': '@minus'}[line[0]] - inlist = 'itemize' - ret += '@item\n' - line = line[2:] - elif lastempty and inlist: - ret += '@end %s\n\n' % inlist - inlist = '' - - lastempty = empty - ret += line + '\n' - - if inlist: - ret += '@end %s\n\n' % inlist - return ret - - -def texi_body(doc): - """Format the main documentation body""" - return texi_format(doc.body.text) - - -def texi_if(ifcond, prefix='\n', suffix='\n'): - """Format the #if condition""" - if not ifcond: - return '' - return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix) - - -def texi_enum_value(value, desc, suffix): - """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n%s%s' % ( - value.name, desc, texi_if(value.ifcond, prefix='@*')) - - -def texi_member(member, desc, suffix): - """Format a table of members item for an object type member""" - typ = member.type.doc_type() - membertype = ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n%s%s' % ( - member.name, membertype, - ' (optional)' if member.optional else '', - suffix, desc, texi_if(member.ifcond, prefix='@*')) - - -def texi_members(doc, what, base=None, variants=None, - member_func=texi_member): - """Format the table of members""" - items = '' - for section in doc.args.values(): - # TODO Drop fallbacks when undocumented members are outlawed - if section.text: - desc = texi_format(section.text) - elif (variants and variants.tag_member == section.member - and not section.member.type.doc_type()): - values = section.member.type.member_names() - members_text = ', '.join(['@t{"%s"}' % v for v in values]) - desc = 'One of ' + members_text + '\n' - else: - desc = 'Not documented\n' - items += member_func(section.member, desc, suffix='') - if base: - items += '@item The members of @code{%s}\n' % base.doc_type() - if variants: - for v in variants.variants: - when = ' when @code{%s} is @t{"%s"}%s' % ( - variants.tag_member.name, v.name, texi_if(v.ifcond, " (", ")")) - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - items += member_func(m, desc='', suffix=when) - else: - items += '@item The members of @code{%s}%s\n' % ( - v.type.doc_type(), when) - if not items: - return '' - return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) - - -def texi_arguments(doc, boxed_arg_type): - if boxed_arg_type: - assert not doc.args - return ('\n@b{Arguments:} the members of @code{%s}\n' - % boxed_arg_type.name) - return texi_members(doc, 'Arguments') - - -def texi_features(doc): - """Format the table of features""" - items = '' - for section in doc.features.values(): - desc = texi_format(section.text) - items += '@item @code{%s}\n%s' % (section.name, desc) - if not items: - return '' - return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items) - - -def texi_sections(doc, ifcond): - """Format additional sections following arguments""" - body = '' - for section in doc.sections: - if section.name: - # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body += '\n@b{%s:}\n' % section.name - if section.name and section.name.startswith('Example'): - body += texi_example(section.text) - else: - body += texi_format(section.text) - body += texi_if(ifcond, suffix='') - return body - - -def texi_type(typ, doc, ifcond, members): - return TYPE_FMT(type=typ, - name=doc.symbol, - body=texi_body(doc), - members=members, - features=texi_features(doc), - sections=texi_sections(doc, ifcond)) - - -def texi_msg(typ, doc, ifcond, members): - return MSG_FMT(type=typ, - name=doc.symbol, - body=texi_body(doc), - members=members, - features=texi_features(doc), - sections=texi_sections(doc, ifcond)) - - -class QAPISchemaGenDocVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._prefix = prefix - self._gen = QAPIGenDoc(self._prefix + 'qapi-doc.texi') - self.cur_doc = None - - def write(self, output_dir): - self._gen.write(output_dir) - - def visit_enum_type(self, name, info, ifcond, features, members, prefix): - doc = self.cur_doc - self._gen.add(texi_type('Enum', doc, ifcond, - texi_members(doc, 'Values', - member_func=texi_enum_value))) - - def visit_object_type(self, name, info, ifcond, features, - base, members, variants): - doc = self.cur_doc - if base and base.is_implicit(): - base = None - self._gen.add(texi_type('Object', doc, ifcond, - texi_members(doc, 'Members', base, variants))) - - def visit_alternate_type(self, name, info, ifcond, features, variants): - doc = self.cur_doc - self._gen.add(texi_type('Alternate', doc, ifcond, - texi_members(doc, 'Members'))) - - def visit_command(self, name, info, ifcond, features, - arg_type, ret_type, gen, success_response, boxed, - allow_oob, allow_preconfig): - doc = self.cur_doc - self._gen.add(texi_msg('Command', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None))) - - def visit_event(self, name, info, ifcond, features, arg_type, boxed): - doc = self.cur_doc - self._gen.add(texi_msg('Event', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None))) - - def symbol(self, doc, entity): - if self._gen._body: - self._gen.add('\n') - self.cur_doc = doc - entity.visit(self) - self.cur_doc = None - - def freeform(self, doc): - assert not doc.args - if self._gen._body: - self._gen.add('\n') - self._gen.add(texi_body(doc) + texi_sections(doc, None)) - - -def gen_doc(schema, output_dir, prefix): - vis = QAPISchemaGenDocVisitor(prefix) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - vis.write(output_dir) diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py index bf5552a4e7f..ca66c82b5b8 100644 --- a/scripts/qapi/gen.py +++ b/scripts/qapi/gen.py @@ -178,13 +178,6 @@ def ifcontext(ifcond, *args): arg.end_if() -class QAPIGenDoc(QAPIGen): - - def _top(self): - return (super()._top() - + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') - - class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor): def __init__(self, prefix, what, blurb, pydoc): diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi deleted file mode 100644 index 29abef33e98..00000000000 --- a/tests/qapi-schema/doc-good.texi +++ /dev/null @@ -1,313 +0,0 @@ -@c AUTOMATICALLY GENERATED, DO NOT MODIFY - -@section Section - -@subsection Subsection - -@strong{with emphasis} -@code{var} @{in braces@} - -@itemize @bullet -@item -List item one -@item -Two, multiple -lines - -@item -Three -Still in list - -@end itemize - -Not in list - -@itemize @minus -@item -Second list -Note: still in list - -@end itemize - -Note: not in list - -@enumerate -@item -Third list -is numbered - -@item -another item - -@end enumerate - -Returns: the King -Since: the first age -Notes: - -@enumerate -@item -Lorem ipsum dolor sit amet - -@item -Ut enim ad minim veniam - -@end enumerate - -Duis aute irure dolor - -Example: - --> in -<- out -Examples: -@itemize @minus -@item -@strong{verbatim} -@item -@{braces@} -@end itemize - - - -@deftp {Enum} Enum - - - -@b{Values:} -@table @asis -@item @code{one} -The @emph{one} @{and only@} -@*@b{If:} @code{defined(IFONE)} -@item @code{two} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{enum-feat} -Also @emph{one} @{and only@} -@end table -@code{two} is undocumented - -@b{If:} @code{defined(IFCOND)} -@end deftp - - - -@deftp {Object} Base - - - -@b{Members:} -@table @asis -@item @code{base1: Enum} -the first member -@end table - -@end deftp - - - -@deftp {Object} Variant1 - -A paragraph - -Another paragraph (but no @code{var}: line) - -@b{Members:} -@table @asis -@item @code{var1: string} -Not documented -@*@b{If:} @code{defined(IFSTR)} -@end table - -@b{Features:} -@table @asis -@item @code{variant1-feat} -a feature -@item @code{member-feat} -a member feature -@end table - -@end deftp - - - -@deftp {Object} Variant2 - - - -@end deftp - - - -@deftp {Object} Object - - - -@b{Members:} -@table @asis -@item The members of @code{Base} -@item The members of @code{Variant1} when @code{base1} is @t{"one"} -@item The members of @code{Variant2} when @code{base1} is @t{"two"} (@b{If:} @code{IFTWO}) -@end table - -@b{Features:} -@table @asis -@item @code{union-feat1} -a feature -@end table - -@end deftp - - - -@deftp {Object} SugaredUnion - - - -@b{Members:} -@table @asis -@item @code{type} -One of @t{"one"}, @t{"two"} -@item @code{data: Variant1} when @code{type} is @t{"one"} -@item @code{data: Variant2} when @code{type} is @t{"two"} (@b{If:} @code{IFTWO}) -@end table - -@b{Features:} -@table @asis -@item @code{union-feat2} -a feature -@end table - -@end deftp - - - -@deftp {Alternate} Alternate - - - -@b{Members:} -@table @asis -@item @code{i: int} -an integer -@code{b} is undocumented -@item @code{b: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{alt-feat} -a feature -@end table - -@end deftp - - -@subsection Another subsection - - -@deftypefn Command {} cmd - - - -@b{Arguments:} -@table @asis -@item @code{arg1: int} -the first argument -@item @code{arg2: string} (optional) -the second -argument -@item @code{arg3: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Note:} -@code{arg3} is undocumented - -@b{Returns:} -@code{Object} - -@b{TODO:} -frobnicate - -@b{Notes:} -@itemize @minus -@item -Lorem ipsum dolor sit amet -@item -Ut enim ad minim veniam - -@end itemize - -Duis aute irure dolor - -@b{Example:} -@example --> in -<- out -@end example - -@b{Examples:} -@example -- *verbatim* -- @{braces@} -@end example - -@b{Since:} -2.10 - -@end deftypefn - - - -@deftypefn Command {} cmd-boxed - -If you're bored enough to read this, go see a video of boxed cats - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Example:} -@example --> in - -<- out -@end example - -@end deftypefn - - - -@deftypefn Event {} EVT-BOXED - - - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{feat3} -a feature -@end table - -@end deftypefn - diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 0c4a6a2936f..f08c902911e 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -206,8 +206,7 @@ test('QAPI schema regression tests', python, args: files('test-qapi.py', schemas diff = find_program('diff') qapi_doc = custom_target('QAPI doc', - output: ['doc-good-qapi-doc.texi', - 'doc-good-qapi-commands.c', 'doc-good-qapi-commands.h', + output: ['doc-good-qapi-commands.c', 'doc-good-qapi-commands.h', 'doc-good-qapi-emit-events.c', 'doc-good-qapi-emit-events.h', 'doc-good-qapi-events.c', 'doc-good-qapi-events.h', 'doc-good-qapi-init-commands.c', 'doc-good-qapi-init-commands.h', @@ -219,12 +218,6 @@ qapi_doc = custom_target('QAPI doc', '-p', 'doc-good-', '@INPUT0@' ], depend_files: qapi_gen_depends) -# "full_path()" needed here to work around -# https://github.com/mesonbuild/meson/issues/7585 -test('QAPI doc', diff, args: ['-b', '-u', files('doc-good.texi'), qapi_doc[0].full_path()], - depends: qapi_doc, - suite: ['qapi-schema', 'qapi-doc']) - # Test the document-comment document generation code by running a test schema # file through Sphinx's plain-text builder and comparing the result against # a golden reference. This is in theory susceptible to failures if Sphinx From patchwork Fri Sep 25 16:23:12 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371455 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=i5/J1hb3; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd0q1W4dz9sR4 for ; Sat, 26 Sep 2020 02:39:23 +1000 (AEST) Received: from localhost ([::1]:51936 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqkj-00081e-7e for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:39:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48070) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVd-0006oD-TX for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:47 -0400 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:39915) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVZ-0006qL-Mh for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:44 -0400 Received: by mail-wr1-x441.google.com with SMTP id k10so1105378wru.6 for ; Fri, 25 Sep 2020 09:23:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cfp9eJVJmCGyE7NM1DFsFZRmLQWVMNY4XbJuSqV3KAI=; b=i5/J1hb3qHNo/FQGX4QOAymq0Lmk0Cy8GpAovH+YRToo/MLhu00S+5gsIZ0G3qX47a hMCmIzl7X5ezXCoEOkcFi4VdZTlBjRMZK4/Q0M0A+g0Kf9cn6swUZtDBFEzT9FpCR8V3 YOOowViK43UOpJFYqI+Eqk0A4GxFFwsPBJ1TXdXd4rhueMtWpPEEKTNffGxO1i/SbfDz 1p8uKYkrVaZX7/TdFHtshWK736rvduP3kkCp+diq/e92IO8bNe2RMayw/LS/Wg0icL21 k9V6SQN1L54amdGyoHJJB/t5FnZb3Kd9v9cP79BKw1cXyelNqJqzl4hG9sJ7QH8bHBuX Q7Cg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cfp9eJVJmCGyE7NM1DFsFZRmLQWVMNY4XbJuSqV3KAI=; b=gkvhbqU01TrpXdPb1WwOgSKuFB1qyEjGU5EEMGHaMvMYy+NB/cSt1RVGOfkjXmp4JD YclqN/iQALkb76KD+sH4VfklKVwiGFDKxVgbWS0sv4pHbeqR3ePFIWpGnpso6wsmo3me GCjEZUb8nFwWfLRPGhatTjxtusrHq/fFv/5qYEbioxnjSD7m9Pm04cxFRJYR5xoAKxSX AwDtivwFRmr0xOnRxYKEKc+s8AMTdO7XV4/NTxTkeGpa/DlWAB7CzsKkR1BRAWxkY9ko 08THXfw1agLvVRIH0lgrO37O31o1wH3TvbzytaEfyc63WNnWY05zxb8cCZ8vM6L5ogKJ 0mkw== X-Gm-Message-State: AOAM530VvFTqsPcrJJtgNw2HrZjnoh3wY6XKTGv1uOkQAKA7syf1ZGA1 TBSrZ8HEZgsUcSIXKc1/tXW49gCHsNP2926s X-Google-Smtp-Source: ABdhPJyHcFlllSzNOHzuzD6DukzWgMn1ZwLoN84O1LiXSHYhPc+Hs3UPFH3H1pYFA0kzx8IIyYLLrg== X-Received: by 2002:a5d:4645:: with SMTP id j5mr4885771wrs.388.1601051019185; Fri, 25 Sep 2020 09:23:39 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:38 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Fri, 25 Sep 2020 17:23:12 +0100 Message-Id: <20200925162316.21205-18-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::441; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x441.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Update the documentation of QAPI document comment syntax to match the new rST backend requirements. The principal changes are: * whitespace is now significant, and multiline definitions must have their second and subsequent lines indented to match the first line * general rST format markup is permitted, not just the small set of markup the old texinfo generator handled. For most things (notably bulleted and itemized lists) the old format is the same as rST was. * Specific things that might trip people up: - instead of *bold* and _italic_ rST has **bold** and *italic* - lists need a preceding and following blank line - a lone literal '*' will need to be backslash-escaped to avoid a rST syntax error * the old leading '|' for example (literal text) blocks is replaced by the standard rST '::' literal block. * we support arbitrary levels of sub- and sub-sub-heading, not just a main and sub-heading like the old texinfo generator Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 83 +++++++++++++++++++++++------------- 1 file changed, 53 insertions(+), 30 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 69eaffac376..7d2479dde82 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -824,23 +824,37 @@ See below for more on definition documentation. Free-form documentation may be used to provide additional text and structuring content. +==== Headings and subheadings ==== + +A free-form documentation comment containing a line which starts with +some '=' symbols and then a space defines a section heading: + + ## + # = This is a top level heading + # + # This is a free-form comment which will go under the + # top level heading. + ## + + ## + # == This is a second level heading + ## + +A heading line must be the first line of the documentation +comment block. + +Section headings must always be correctly nested, so you can only +define a third-level heading inside a second-level heading, and so on. ==== Documentation markup ==== -Comment text starting with '=' is a section title: +Documentation comments can use most rST markup. In particular, +a '::' literal block can be used for examples: - # = Section title - -Double the '=' for a subsection title: - - # == Subsection title - -Both are only permitted in free-form documentation. - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines '*' starts an itemized list: @@ -856,34 +870,33 @@ A decimal number followed by '.' starts a numbered list: # multiple lines # 2. Second item -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. +The actual number doesn't matter. -Lists can't be nested. Blank lines are currently not supported within -lists. +Lists of either kind must be preceded and followed by a blank line. +If a list item's text spans multiple lines, then the second and +subsequent lines must be correctly indented to line up with the +first character of the first line. -Additional whitespace between the initial '#' and the comment text is -permitted. - -*foo* and _foo_ are for strong and emphasis styles respectively (they -do not work over multiple lines). @foo is used to reference a name in -the schema. +The usual '**strong**', '*emphasised*' and '``literal``' markup should +be used. If you need a single literal '*' you will need to +backslash-escape it. As an extension beyond the usual rST syntax, you +can also use '@foo' to reference a name in the schema; this is +rendered the same way as '``foo``'. Example: ## -# = Section -# == Subsection -# -# Some text foo with *strong* and _emphasis_ +# Some text foo with **bold** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## @@ -937,6 +950,16 @@ multiline argument descriptions. A 'Since: x.y.z' tagged section lists the release that introduced the definition. +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first. + +An 'Example' or 'Examples' section is automatically rendered +entirely as literal fixed-width text. In other sections, +the text is formatted, and rST markup can be used. + For example: ## From patchwork Fri Sep 25 16:23:13 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371461 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=jBy0Y+QM; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd4H73YQz9sR4 for ; Sat, 26 Sep 2020 02:42:23 +1000 (AEST) Received: from localhost ([::1]:60232 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqnd-0003LB-Ub for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:42:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48116) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVj-0006qo-IS for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:53 -0400 Received: from mail-wm1-x330.google.com ([2a00:1450:4864:20::330]:35699) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVc-0006qf-9j for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:49 -0400 Received: by mail-wm1-x330.google.com with SMTP id y15so3947909wmi.0 for ; Fri, 25 Sep 2020 09:23:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=iwFfx7IHL9x9dKiKzfGrb8UOIhEkDUw+GxDh1l0H7Jo=; b=jBy0Y+QMiFxiSrw7XyZNspBN1EXiJfSsgwWb3CbsEwy4fhlJ2P4UsMF2hN/2ITuzhc XEmVl2BFPhLtE3KBXPYbR76i1CoiSrMCtRbPMZDTHGOEkoKDIUDlkk0RZsbIzjMiOyPA h0erwhloQWGMreWD4a9UR7AiHxBcX2dyZbWbTLIW6hu4dFTnUW4Ds8G33ACZf/Ux/sqA MTjYNCwao8iv+D1l9tQZPVf04PcdQaFL5OZZKl29j2Fqa54Z8kScZHJ2zFlok2cjUjPy 5L0WIyoVXEkQbeINTZyP7+ID5HDRKDWscsLEGE4xMx6CXeiPanrPNZIvvrOY3CpeO/v7 OlOA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=iwFfx7IHL9x9dKiKzfGrb8UOIhEkDUw+GxDh1l0H7Jo=; b=SUsK/YgV8xo2E09W+99zd1gOyaBn6Is9pm4JlSqte/DDpqTXVoUg6DEabjAfCKAiEN OFB6PkPnZqlAkdnpAGCBUUMaYacYuZ92uKnIdXgcndqvXxW32go8VJsSNDwqewg37OPH I8KtvSZuUZbzQK94deHR+DhpGHsOJgeWJO3DT4aw+Z0rqWR5BuXjt12DwFHUEXvcndm7 fVntTkdlrtvhJnvTzlaqKUOWYqu8x9LgFS8/nDtrd+marVVQBh7C3uuoVi7hNy0HVZPw 4eDe5GBTqVn8oID9+F1Nx+JS35txQEnmUGucCbaksu0Np2op0u175D1hLWTzdlxne1f5 OClw== X-Gm-Message-State: AOAM530JmMhMM3oqWhvgRwEdCKzTuS0JL7s8f2/ZVslDqaU8ETW0YVpt QMbpHhjSpIk5s+OCsYrHurFEr81Znq05Phm6 X-Google-Smtp-Source: ABdhPJwlx7dQcTynDTPhMLk/axQbRllvRepXm9X0U7XerjcnPkMLnpX2WzfCW2x+8cFbLvtepRSYsQ== X-Received: by 2002:a1c:4c0d:: with SMTP id z13mr3758768wmf.113.1601051020659; Fri, 25 Sep 2020 09:23:40 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:39 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 18/21] scripts/texi2pod: Delete unused script Date: Fri, 25 Sep 2020 17:23:13 +0100 Message-Id: <20200925162316.21205-19-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::330; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x330.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We no longer need the texi2pod script, so we can delete it, and the special-casing it had in the checkpatch script. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- scripts/checkpatch.pl | 2 +- scripts/texi2pod.pl | 536 ------------------------------------------ 2 files changed, 1 insertion(+), 537 deletions(-) delete mode 100755 scripts/texi2pod.pl diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 50910899f2e..1ba8a3810b6 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -1659,7 +1659,7 @@ sub process { # tabs are only allowed in assembly source code, and in # some scripts we imported from other projects. next if ($realfile =~ /\.(s|S)$/); - next if ($realfile =~ /(checkpatch|get_maintainer|texi2pod)\.pl$/); + next if ($realfile =~ /(checkpatch|get_maintainer)\.pl$/); if ($rawline =~ /^\+.*\t/) { my $herevet = "$here\n" . cat_vet($rawline) . "\n"; diff --git a/scripts/texi2pod.pl b/scripts/texi2pod.pl deleted file mode 100755 index 8bfc6f6f4c4..00000000000 --- a/scripts/texi2pod.pl +++ /dev/null @@ -1,536 +0,0 @@ -#! /usr/bin/env perl - -# Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc. - -# This file is part of GCC. - -# GCC is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# GCC is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GCC; see the file COPYING. If not, -# see . - -# This does trivial (and I mean _trivial_) conversion of Texinfo -# markup to Perl POD format. It's intended to be used to extract -# something suitable for a manpage from a Texinfo document. - -use warnings; - -$output = 0; -$skipping = 0; -%sects = (); -$section = ""; -@icstack = (); -@endwstack = (); -@skstack = (); -@instack = (); -$shift = ""; -%defs = (); -$fnno = 1; -$inf = ""; -$ibase = ""; -@ipath = (); -$encoding = undef; -@args = (); - -while ($_ = shift) { - if (/^-D(.*)$/) { - if ($1 ne "") { - $flag = $1; - } else { - $flag = shift; - } - $value = ""; - ($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/); - die "no flag specified for -D\n" - unless $flag ne ""; - die "flags may only contain letters, digits, hyphens, dashes and underscores\n" - unless $flag =~ /^[a-zA-Z0-9_-]+$/; - $defs{$flag} = $value; - } elsif (/^-I(.*)$/) { - if ($1 ne "") { - $flag = $1; - } else { - $flag = shift; - } - push (@ipath, $flag); - } elsif (/^-/) { - usage(); - } else { - $in = $_, next unless defined $in; - $out = $_, next unless defined $out; - usage(); - } -} - -if (defined $in) { - $inf = gensym(); - open($inf, "<$in") or die "opening \"$in\": $!\n"; - $ibase = $1 if $in =~ m|^(.+)/[^/]+$|; -} else { - $inf = \*STDIN; -} - -if (defined $out) { - open(STDOUT, ">$out") or die "opening \"$out\": $!\n"; -} - -while(defined $inf) { -while(<$inf>) { - # Certain commands are discarded without further processing. - /^\@(?: - [a-z]+index # @*index: useful only in complete manual - |need # @need: useful only in printed manual - |(?:end\s+)?group # @group .. @end group: ditto - |page # @page: ditto - |node # @node: useful only in .info file - |(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents - )\b/x and next; - - chomp; - - # Look for filename and title markers. - /^\@setfilename\s+([^.]+)/ and $fn = $1, next; - /^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next; - - # Look for document encoding - /^\@documentencoding\s+([^.]+)/ and do { - $encoding = $1 unless defined $encoding; - next; - }; - - # Identify a man title but keep only the one we are interested in. - /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do { - if (exists $defs{$1}) { - $fn = $1; - $tl = postprocess($2); - } - next; - }; - - # Look for blocks surrounded by @c man begin SECTION ... @c man end. - # This really oughta be @ifman ... @end ifman and the like, but such - # would require rev'ing all other Texinfo translators. - /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do { - $output = 1 if exists $defs{$2}; - $sect = $1; - next; - }; - /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next; - /^\@c\s+man\s+end/ and do { - $sects{$sect} = "" unless exists $sects{$sect}; - $sects{$sect} .= postprocess($section); - $section = ""; - $output = 0; - next; - }; - - # handle variables - /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do { - $defs{$1} = $2; - next; - }; - /^\@clear\s+([a-zA-Z0-9_-]+)/ and do { - delete $defs{$1}; - next; - }; - - # Single line command handlers. - - /^\@include\s+(.+)$/ and do { - push @instack, $inf; - $inf = gensym(); - $file = postprocess($1); - - # Try cwd and $ibase, then explicit -I paths. - $done = 0; - foreach $path ("", $ibase, @ipath) { - $mypath = $file; - $mypath = $path . "/" . $mypath if ($path ne ""); - open($inf, "<" . $mypath) and ($done = 1, last); - } - die "cannot find $file" if !$done; - next; - }; - - next unless $output; - - # Discard comments. (Can't do it above, because then we'd never see - # @c man lines.) - /^\@c\b/ and next; - - # End-block handler goes up here because it needs to operate even - # if we are skipping. - /^\@end\s+([a-z]+)/ and do { - # Ignore @end foo, where foo is not an operation which may - # cause us to skip, if we are presently skipping. - my $ended = $1; - next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex|copying)$/; - - die "\@end $ended without \@$ended at line $.\n" unless defined $endw; - die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw; - - $endw = pop @endwstack; - - if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) { - $skipping = pop @skstack; - next; - } elsif ($ended =~ /^(?:example|smallexample|display - |quotation|deftp|deftypefn)$/x) { - $shift = ""; - $_ = ""; # need a paragraph break - } elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) { - $_ = "\n=back\n"; - $ic = pop @icstack; - } elsif ($ended eq "multitable") { - $_ = "\n=back\n"; - } else { - die "unknown command \@end $ended at line $.\n"; - } - }; - - # We must handle commands which can cause skipping even while we - # are skipping, otherwise we will not process nested conditionals - # correctly. - /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = "ifset"; - $skipping = 1 unless exists $defs{$1}; - next; - }; - - /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = "ifclear"; - $skipping = 1 if exists $defs{$1}; - next; - }; - - /^\@(ignore|menu|iftex|copying)\b/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = $1; - $skipping = 1; - next; - }; - - next if $skipping; - - # Character entities. First the ones that can be replaced by raw text - # or discarded outright: - s/\@copyright\{\}/(c)/g; - s/\@dots\{\}/.../g; - s/\@enddots\{\}/..../g; - s/\@([.!? ])/$1/g; - s/\@[:-]//g; - s/\@bullet(?:\{\})?/*/g; - s/\@TeX\{\}/TeX/g; - s/\@pounds\{\}/\#/g; - s/\@minus(?:\{\})?/-/g; - s/\\,/,/g; - - # Now the ones that have to be replaced by special escapes - # (which will be turned back into text by unmunge()) - s/&/&/g; - s/\@\{/{/g; - s/\@\}/}/g; - s/\@\@/&at;/g; - - # Inside a verbatim block, handle @var specially. - if ($shift ne "") { - s/\@var\{([^\}]*)\}/<$1>/g; - } - - # POD doesn't interpret E<> inside a verbatim block. - if ($shift eq "") { - s//>/g; - } else { - s//>/g; - } - - /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ - and $_ = "\n=head2 $1\n"; - /^\@subsection\s+(.+)$/ - and $_ = "\n=head3 $1\n"; - /^\@subsubsection\s+(.+)$/ - and $_ = "\n=head4 $1\n"; - - # Block command handlers: - /^\@itemize(?:\s+(\@[a-z]+|\*|-))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic = $1; - } else { - $ic = '*'; - } - $_ = "\n=over 4\n"; - $endw = "itemize"; - }; - - /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic = $1 . "."; - } else { - $ic = "1."; - } - $_ = "\n=over 4\n"; - $endw = "enumerate"; - }; - - /^\@multitable\s.*/ and do { - push @endwstack, $endw; - $endw = "multitable"; - $_ = "\n=over 4\n"; - }; - - /^\@([fv]?table)\s+(\@[a-z]+)/ and do { - push @endwstack, $endw; - push @icstack, $ic; - $endw = $1; - $ic = $2; - $ic =~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/; - $ic =~ s/\@(?:code|kbd)/C/; - $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/; - $ic =~ s/\@(?:file)/F/; - $ic =~ s/\@(?:asis)//; - $_ = "\n=over 4\n"; - }; - - /^\@((?:small)?example|display)/ and do { - push @endwstack, $endw; - $endw = $1; - $shift = "\t"; - $_ = ""; # need a paragraph break - }; - - /^\@item\s+(.*\S)\s*$/ and $endw eq "multitable" and do { - @columns = (); - for $column (split (/\s*\@tab\s*/, $1)) { - # @strong{...} is used a @headitem work-alike - $column =~ s/^\@strong\{(.*)\}$/$1/; - push @columns, $column; - } - $_ = "\n=item ".join (" : ", @columns)."\n"; - }; - - /^\@(quotation)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw = $1; - $_ = "\n$2:" - }; - - /^{(.*)}$|^(.*)$/ and $#args > 0 and do { - $kind = $args[0]; - $arguments = $1 // ""; - if ($endw eq "deftypefn") { - $ret = $args[1]; - $fname = "B<$args[2]>"; - $_ = $ret ? "$ret " : ""; - $_ .= "$fname $arguments ($kind)"; - } else { - $_ = "B<$args[1]> ($kind)\n\n$arguments"; - } - @args = (); - }; - - /^\@(deftp)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw = $1; - $arg = $2; - $arg =~ s/{([^}]*)}/$1/g; - $arg =~ s/\@$//; - @args = split (/ /, $arg); - $_ = ""; - }; - - /^\@(deftypefn)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw = $1; - $arg = $2; - $arg =~ s/{([^}]*)}/$1/g; - $arg =~ s/\@$//; - @args = split (/ /, $arg); - $_ = ""; - }; - - /^\@itemx?\s*(.+)?$/ and do { - if (defined $1) { - if ($ic eq "") { - $_ = "\n=item $1\n"; - } else { - # Entity escapes prevent munging by the <> processing below. - $_ = "\n=item $ic\<$1\>\n"; - } - } else { - $_ = "\n=item $ic\n"; - $ic =~ y/A-Ya-y/B-Zb-z/; - $ic =~ s/(\d+)/$1 + 1/eg; - } - }; - - $section .= $shift.$_."\n"; -} -# End of current file. -close($inf); -$inf = pop @instack; -} - -die "No filename or title\n" unless defined $fn && defined $tl; - -print "=encoding $encoding\n\n" if defined $encoding; - -$sects{NAME} = "$fn \- $tl\n"; -$sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES}; - -for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES - BUGS NOTES FOOTNOTES EXAMPLES SEEALSO AUTHOR COPYRIGHT)) { - if(exists $sects{$sect}) { - $head = $sect; - $head =~ s/SEEALSO/SEE ALSO/; - print "=head1 $head\n\n"; - print scalar unmunge ($sects{$sect}); - print "\n"; - } -} - -sub usage -{ - die "usage: $0 [-D toggle...] [infile [outfile]]\n"; -} - -sub postprocess -{ - local $_ = $_[0]; - - # @value{foo} is replaced by whatever 'foo' is defined as. - while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) { - if (! exists $defs{$2}) { - print STDERR "Option $2 not defined\n"; - s/\Q$1\E//; - } else { - $value = $defs{$2}; - s/\Q$1\E/$value/; - } - } - - # Formatting commands. - # Temporary escape for @r. - s/\@r\{([^\}]*)\}/R<$1>/g; - s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; - s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; - s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g; - s/\@sc\{([^\}]*)\}/\U$1/g; - s/\@file\{([^\}]*)\}/F<$1>/g; - s/\@w\{([^\}]*)\}/S<$1>/g; - s/\@t\{([^\}]*)\}/$1/g; - s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; - - # keep references of the form @ref{...}, print them bold - s/\@(?:ref)\{([^\}]*)\}/B<$1>/g; - - # Change double single quotes to double quotes. - s/''/"/g; - s/``/"/g; - - # Cross references are thrown away, as are @noindent and @refill. - # (@noindent is impossible in .pod, and @refill is unnecessary.) - # @* is also impossible in .pod; we discard it and any newline that - # follows it. Similarly, our macro @gol must be discarded. - - s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; - s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; - s/;\s+\@pxref\{(?:[^\}]*)\}//g; - s/\@noindent\s*//g; - s/\@refill//g; - s/\@gol//g; - s/\@\*\s*\n?//g; - - # Anchors are thrown away - s/\@anchor\{(?:[^\}]*)\}//g; - - # @uref can take one, two, or three arguments, with different - # semantics each time. @url and @email are just like @uref with - # one argument, for our purposes. - s/\@(?:uref|url|email)\{([^\},]*)\}/<B<$1>>/g; - s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; - s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; - - # Un-escape <> at this point. - s/<//g; - - # Now un-nest all B<>, I<>, R<>. Theoretically we could have - # indefinitely deep nesting; in practice, one level suffices. - 1 while s/([BIR])<([^<>]*)([BIR])<([^<>]*)>/$1<$2>$3<$4>$1 with bare ...; eliminate empty markup, B<>; - # shift white space at the ends of [BI]<...> expressions outside - # the expression. - s/R<([^<>]*)>/$1/g; - s/[BI]<>//g; - s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g; - s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g; - - # Extract footnotes. This has to be done after all other - # processing because otherwise the regexp will choke on formatting - # inside @footnote. - while (/\@footnote/g) { - s/\@footnote\{([^\}]+)\}/[$fnno]/; - add_footnote($1, $fnno); - $fnno++; - } - - return $_; -} - -sub unmunge -{ - # Replace escaped symbols with their equivalents. - local $_ = $_[0]; - - s/</E/g; - s/>/E/g; - s/{/\{/g; - s/}/\}/g; - s/&at;/\@/g; - s/&/&/g; - return $_; -} - -sub add_footnote -{ - unless (exists $sects{FOOTNOTES}) { - $sects{FOOTNOTES} = "\n=over 4\n\n"; - } - - $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++; - $sects{FOOTNOTES} .= $_[0]; - $sects{FOOTNOTES} .= "\n\n"; -} - -# stolen from Symbol.pm -{ - my $genseq = 0; - sub gensym - { - my $name = "GEN" . $genseq++; - my $ref = \*{$name}; - delete $::{$name}; - return $ref; - } -} From patchwork Fri Sep 25 16:23:14 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371464 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=V7LMJc0S; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Byd8F751Fz9sS8 for ; Sat, 26 Sep 2020 02:45:49 +1000 (AEST) Received: from localhost ([::1]:39964 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqqx-0006tv-VQ for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:45:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48112) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVf-0006pI-S4 for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:49 -0400 Received: from mail-wm1-x32b.google.com ([2a00:1450:4864:20::32b]:51694) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVd-0006qj-K4 for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:47 -0400 Received: by mail-wm1-x32b.google.com with SMTP id w2so3638408wmi.1 for ; Fri, 25 Sep 2020 09:23:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=25BY9m20F0UzEdPJ4XVHRzjKq1kcqLKFnuqSO6foM7U=; b=V7LMJc0SH/KrNoOhaDblTimtLfZTqHIS5Qv2WRAZCiG46ZFJFHjNp34/vYNDSLn1CQ Z0pP/xB9/UQA1L2whFTNKhrsiOxiaRqALIjilzblWyOPT468+ioryiTqZVzD9te2WS2B hk+feWKMdOG1zqTd/PENuAAfyDb1kuonZ01IL/qI9SGYxUsdnQtfVos8UT2i7R8C1iNP Y+e2p24hueYItebGKUuqgmPwq3DeQ3m3zUCpEQIQJGeXgUFiHimV0CwI70XOwz6vWjRQ avhCJExohyMkPu4x65vPwjWO8hM5JgeVD7Mn/m+lUWuuQPfx1YCYuqEUDBVMGfCJOT6z Ck3Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=25BY9m20F0UzEdPJ4XVHRzjKq1kcqLKFnuqSO6foM7U=; b=prOSN3kbEIWfRYgBPezgdK6oPsujGE3f8P1TRocdq+oeItT3IZ3ypyGOJN/3lxNy6k H65KdnwVHK24d3x0/9BaY6qUFtf3T1tBLF4TIJQRHTccQ1O244XkEjB18A6mWPxBoiNN 1kEwwDxDueoSzuR3Ic8B51a9RM0izEWgRF9MDh7UD1ZADTMTffNuRnww1uQZvJcQwvTh nhk5LbKWKb0fGUSevZwwU9g0aXW0vWFVHBaEAt4bx/lGk6/Aj7QRIegRo+ZnUMoJQR7I +cDYKTuUML5Am1zMF4u0H1O32F8p00VIdQtZ/E4qf3XMqhOTllBbSm64v5PCHNk46Y5f qT5A== X-Gm-Message-State: AOAM533BxZsJPnWavZLqhrscvM4XktK17Qi5/Hq66bxIeyXbj6B3dMrH S84g6Ou/w4XXJa7KjfnpIvGktZEFegHRkWad X-Google-Smtp-Source: ABdhPJy1dL/KBbKc3Kle4EouFaQeLJVlTYmHrfn89uJ80k+KRZWJfKQmuSUPjR0bXPdAhGy2mE/I6w== X-Received: by 2002:a1c:3d44:: with SMTP id k65mr3844075wma.132.1601051021547; Fri, 25 Sep 2020 09:23:41 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:40 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 19/21] Remove Texinfo related line from git.orderfile Date: Fri, 25 Sep 2020 17:23:14 +0100 Message-Id: <20200925162316.21205-20-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32b; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32b.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We don't use Texinfo any more; we can remove the references to the .texi source file from our git.orderfile. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- scripts/git.orderfile | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/git.orderfile b/scripts/git.orderfile index a021afc2d51..3736c1d6aff 100644 --- a/scripts/git.orderfile +++ b/scripts/git.orderfile @@ -12,7 +12,6 @@ # Documentation docs/* *.rst -*.texi # build system configure From patchwork Fri Sep 25 16:23:15 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371466 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=nSuXRZn+; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4BydCc4BLMz9sR4 for ; Sat, 26 Sep 2020 02:48:42 +1000 (AEST) Received: from localhost ([::1]:46146 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqtk-00019v-2J for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:48:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48118) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVj-0006qs-Kk for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:53 -0400 Received: from mail-wm1-x333.google.com ([2a00:1450:4864:20::333]:35702) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVd-0006qs-Kl for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:51 -0400 Received: by mail-wm1-x333.google.com with SMTP id y15so3947997wmi.0 for ; Fri, 25 Sep 2020 09:23:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=IBvSe9U4y9OyrW59Pq+7GIi7CePKnagVOSmaXWRdN60=; b=nSuXRZn+qUU5qIYn5Y7l1NVzBY+e1Ew+5TO241KwdWoxEK0KN4Iwl0V+LFOEheZjlO hKdWPZ6Fv+28M/kmUUW+teDzI5X/4YGJT7eKg6pfQZWOOXBXn+oFZ4/hfw62RvJMuMvF NOwXocmtppq30VPBXIurhtePfmd6RWy9Qu4vEM2ySMBYTkD43By65fzhfux9zGXfGrh6 ilG+J07fAwUNbIVQhZ3OciCxmyBhudau35DQUW5yCUfnmQSd9CKVMqbH5vVF48qk8IjJ u0ib3lBddIdIQOnHAFLkY73pHU1ka37YCG3Zwau72yOjMU/+Sr2+bDemtf1jeprN/P9E pf0A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=IBvSe9U4y9OyrW59Pq+7GIi7CePKnagVOSmaXWRdN60=; b=klp3gpeo7rAiqCP5LBbffHk344XLsc9iUrGqyBQiQ3qskAGlUopmRIi0eSXMZ9IQ57 be1YY+LHzDHBQv96mVjTzZ99vwtcg0gNyqDTqT3afPQ0lJrEiiNl2t5Md2qVfemhae7Q oYe4j7f1BYUPkXvIhLfhOFZCLK6Tj8v8cLN2b5mpJfvqRz+iizHXsxY+wdLdwuXusGTK NMvmoR95THno+tDdoseeiXogXkBgIJWJYgOlVegYSzd9lP4hr6tL6vdvn8V5mUy5vtaP A08YcW40hxHdCQh6JN4BGiJF4PhRsvTLN16UrL6OPWNPFKvJ/xrzB4CzNYNcOZSamsIY z4Jw== X-Gm-Message-State: AOAM531ewFqDkc5e2cXBySn9HnI6eDDpG62W3sFPXdADSsFAEij4gmZV VPzFJYnd/jLBN5ntYm6MctuyxQ1I6oHwAsyE X-Google-Smtp-Source: ABdhPJzNvXY+iL3QOA8WWmeGgC7/LfSm1SsgDKUSW6sdIl25Xh3TnKbcbkQC//HJtKf5i64bobIQKQ== X-Received: by 2002:a1c:9c8c:: with SMTP id f134mr3951436wme.27.1601051022631; Fri, 25 Sep 2020 09:23:42 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:42 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 20/21] configure: Drop texinfo requirement Date: Fri, 25 Sep 2020 17:23:15 +0100 Message-Id: <20200925162316.21205-21-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::333; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x333.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We don't need the texinfo and pod2man programs to build our documentation any more, so remove them from configure's tests. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- configure | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/configure b/configure index e8e8e984f24..190d88ffa37 100755 --- a/configure +++ b/configure @@ -4873,14 +4873,14 @@ if test "$docs" != "no" ; then else sphinx_ok=no fi - if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then + if test "$sphinx_ok" = "yes"; then docs=yes else if test "$docs" = "yes" ; then if has $sphinx_build && test "$sphinx_ok" != "yes"; then echo "Warning: $sphinx_build exists but it is either too old or uses too old a Python version" >&2 fi - feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx" + feature_not_found "docs" "Install a Python 3 version of python-sphinx" fi docs=no fi @@ -6300,13 +6300,6 @@ if test "$solaris" = "no" && test "$tsan" = "no"; then fi fi -# test if pod2man has --utf8 option -if pod2man --help | grep -q utf8; then - POD2MAN="pod2man --utf8" -else - POD2MAN="pod2man" -fi - # Use ASLR, no-SEH and DEP if available if test "$mingw32" = "yes" ; then for flag in --dynamicbase --no-seh --nxcompat; do @@ -7455,7 +7448,6 @@ echo "HOST_DSOSUF=$HOST_DSOSUF" >> $config_host_mak echo "LIBS_QGA=$libs_qga" >> $config_host_mak echo "TASN1_LIBS=$tasn1_libs" >> $config_host_mak echo "TASN1_CFLAGS=$tasn1_cflags" >> $config_host_mak -echo "POD2MAN=$POD2MAN" >> $config_host_mak if test "$gcov" = "yes" ; then echo "CONFIG_GCOV=y" >> $config_host_mak fi From patchwork Fri Sep 25 16:23:16 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1371446 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=mJcq0Y3g; dkim-atps=neutral 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 ozlabs.org (Postfix) with ESMTPS id 4Bycsc5thtz9sTQ for ; Sat, 26 Sep 2020 02:33:08 +1000 (AEST) Received: from localhost ([::1]:34624 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kLqeg-0000WC-Ny for incoming@patchwork.ozlabs.org; Fri, 25 Sep 2020 12:33:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48120) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kLqVk-0006r2-Ov for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:53 -0400 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:45578) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kLqVd-0006r1-Kc for qemu-devel@nongnu.org; Fri, 25 Sep 2020 12:23:52 -0400 Received: by mail-wr1-x42f.google.com with SMTP id x14so4188972wrl.12 for ; Fri, 25 Sep 2020 09:23:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=b27CB/FmLq2oeiHU/6zkG//hh/Oo3LelbsnNKWwTVM0=; b=mJcq0Y3gXrYSpPTPJph+oe7Hk6EcpnrqiXnRYlcQDAqYpWTdWUqyf8eaYjiDfiS1tr iYFY+ooUbp9LftEXgBLdM6AU1XTGcPL3AbtC0kvbCZVUxVNDxU9YOhw4xzg+2MLIRdXg FjKpscamNXutxB8n1I8MSJb2lClwiPs2t4OM6JNNlZm/Ltjk7rNNr5a9Ko7wBpqtI3da yD9lEC18vw5HEx4BRQvimXWHXTxU9ETu1abjtQGbZrqrdxwGjYQuV+R+laBVcDJ95Xcy ocv+4VEEV6wgNifJaSvnRQdlWCQTerpMwQn0ZTXkTck5+PF57I8Hx8GVL2aq3cRjZglN XZYg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=b27CB/FmLq2oeiHU/6zkG//hh/Oo3LelbsnNKWwTVM0=; b=Mw8GVR+Z2DUp8iBroEIAiHe2Fm2GvvdiTXSTWpMj2mUlL7aBhxqm4eWDAiEjBbrM0J xPULwn1k//y/FX722JHI4H2757CbQupCiErGrl7vPQHHXt7bvgw1eGPqXCAvt2OzmqVa KsdK4EOOjksDMDo1bIgufTOxRQSDDiXJbLBT2qAASgPyB2EWEU3lx0UPvzSFuiWOAf9O won1GvcbRhHyWItlZSiplY77Na9ugLka3juWolbQ95MLUiFliPq/4KHB+5N6AiCRJCGi k+BXeNNSjZkJejbudZ8x8EwA0QaL5kXLOEddVYyfKT6FJuWfgXRs2sJslQ/x4lsZ8N+c sdAw== X-Gm-Message-State: AOAM533uzCE3HBfy73tapjVtNP9f0HzY6ehL8wU9Gf2l96fbV79uhJhI a76mlz5RnRuQ8h7Epo+t4SQreC67JfzD4ume X-Google-Smtp-Source: ABdhPJzJ8GJ+YKnhZSKrRwC0abwgx3fEXOmgpHP1yt0fqAcywFqiwIJJf56hYB3MWSZzrNk26aeXkg== X-Received: by 2002:a5d:4744:: with SMTP id o4mr5299974wrs.130.1601051023800; Fri, 25 Sep 2020 09:23:43 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d6sm3565824wrq.67.2020.09.25.09.23.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 25 Sep 2020 09:23:43 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v6 21/21] Remove texinfo dependency from docker and CI configs Date: Fri, 25 Sep 2020 17:23:16 +0100 Message-Id: <20200925162316.21205-22-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200925162316.21205-1-peter.maydell@linaro.org> References: <20200925162316.21205-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::42f; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42f.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. 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, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: John Snow , Markus Armbruster Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We don't need texinfo to build the docs any more, so we can drop that dependency from our docker and other CI configs. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- .travis.yml | 1 - scripts/coverity-scan/coverity-scan.docker | 1 - tests/docker/dockerfiles/debian10.docker | 1 - tests/docker/dockerfiles/fedora.docker | 1 - tests/docker/dockerfiles/ubuntu.docker | 1 - tests/docker/dockerfiles/ubuntu1804.docker | 1 - tests/docker/dockerfiles/ubuntu2004.docker | 1 - 7 files changed, 7 deletions(-) diff --git a/.travis.yml b/.travis.yml index c75221dca3e..bd9a6fc06cc 100644 --- a/.travis.yml +++ b/.travis.yml @@ -192,7 +192,6 @@ jobs: apt: packages: - python3-sphinx - - texinfo - perl diff --git a/scripts/coverity-scan/coverity-scan.docker b/scripts/coverity-scan/coverity-scan.docker index 018c03de6d5..501ac672332 100644 --- a/scripts/coverity-scan/coverity-scan.docker +++ b/scripts/coverity-scan/coverity-scan.docker @@ -110,7 +110,6 @@ ENV PACKAGES \ systemd-devel \ systemtap-sdt-devel \ tar \ - texinfo \ usbredir-devel \ virglrenderer-devel \ vte291-devel \ diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/dockerfiles/debian10.docker index e3c11a454ee..1e4188ba225 100644 --- a/tests/docker/dockerfiles/debian10.docker +++ b/tests/docker/dockerfiles/debian10.docker @@ -31,7 +31,6 @@ RUN apt update && \ python3 \ python3-setuptools \ python3-sphinx \ - texinfo \ $(apt-get -s build-dep qemu | egrep ^Inst | fgrep '[all]' | cut -d\ -f2) ENV FEATURES docs diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfiles/fedora.docker index 70b6186bd3e..71e4b569770 100644 --- a/tests/docker/dockerfiles/fedora.docker +++ b/tests/docker/dockerfiles/fedora.docker @@ -96,7 +96,6 @@ ENV PACKAGES \ tar \ tesseract \ tesseract-langpack-eng \ - texinfo \ usbredir-devel \ virglrenderer-devel \ vte291-devel \ diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfiles/ubuntu.docker index 161806e6b8c..b556ed17d29 100644 --- a/tests/docker/dockerfiles/ubuntu.docker +++ b/tests/docker/dockerfiles/ubuntu.docker @@ -63,7 +63,6 @@ ENV PACKAGES \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dockerfiles/ubuntu1804.docker index a10ea2850b6..a6a7617da67 100644 --- a/tests/docker/dockerfiles/ubuntu1804.docker +++ b/tests/docker/dockerfiles/ubuntu1804.docker @@ -49,7 +49,6 @@ ENV PACKAGES \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu2004.docker b/tests/docker/dockerfiles/ubuntu2004.docker index 8d10934a2a7..cafe8443fbf 100644 --- a/tests/docker/dockerfiles/ubuntu2004.docker +++ b/tests/docker/dockerfiles/ubuntu2004.docker @@ -57,7 +57,6 @@ ENV PACKAGES flex bison \ sparse \ tesseract-ocr \ tesseract-ocr-eng \ - texinfo \ xfslibs-dev\ vim RUN apt-get update && \