From patchwork Tue Feb 25 14:04:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403921 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id B23121395 for ; Tue, 25 Feb 2020 14:05:35 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 85EA520578 for ; Tue, 25 Feb 2020 14:05:35 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="Z/3POFqV" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 85EA520578 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57062 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6aq6-0007vv-LP for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:05:34 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44738) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apM-0006dL-2x for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:51 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apI-0005GQ-44 for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:47 -0500 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]:38717) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apH-0005GC-UM for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:44 -0500 Received: by mail-wm1-x32d.google.com with SMTP id a9so3276393wmj.3 for ; Tue, 25 Feb 2020 06:04:43 -0800 (PST) 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=vZTPlHR8mq3OwOYR6l43zxathKAQyqG0FYbXCshk6J4=; b=Z/3POFqVqkDwutjXFMDFZqtO2SQ1a7fSQtn0yyQSw2WKpkEataB9QeJymxVIre3FqU JSufsQZefWgUSWT975NRzrZ9PbfPSglgBV9eiFe08yZ57Hi3axmktvWZSTAFiaAhLl6U vnrBsJTtkY9jyx5HQB9enFRiaSSG/4F3LSmDv9Toe1jmJD6Sph0kYdAzFf0AVmEUEbKH ZXOn/86inFEGgf9O2D5+Nn470ewwtrMIcBTcl6g36gaBaVkB/8iwwbdj86suxCL5p2Dm EMRu98W6E36WdJeFwCXbyoO9XM3uF/WP9oVNJWTpXyZzqa6iraxIxkW1A4UT0G8qw5Tf ZLdw== 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=vZTPlHR8mq3OwOYR6l43zxathKAQyqG0FYbXCshk6J4=; b=FJApJeXv9ISDcZY5q+GbeJvcv0dVNn8YW0m06TAA5X360xu5wiwkBMoCUFr+pP8ESM 2471jR4OcWnSeIks/OjrxBu0A+qGymLuolW5Bv6HA93rjE/GGfvNbQ0VUmokDn8c8QiL HR7lRBAqzjZyhrtEarTU165Dvq7+7jBDI9xc73AdISV31P4gCxVY7HCtkXHFVeQ5bQQM x1TL8U0m1ievDG6to2QO3YCqvDO41d6DDnI9sWa0FB7PZGB7hQN6KkGNG/NQjcoEMoLi dOBPRgtstHQFPugRNqplnNav9DgeTleUMVQ67smfNF48foOobL1/UVPvBECsDCaZ6It1 zcUA== X-Gm-Message-State: APjAAAXX36UaPS7qLHrAzZzvRk71FmC21HA0ZNw7ftV/jYNulIkEHROp z84Yowt7x9Oyvo9yM2Oj4XObx/f+w8rsfA== X-Google-Smtp-Source: APXvYqysEvs3G457ycrw59VlVrisMA8rb1Lkd0E0xAk/BT9yn7egokJoaT44iZjwx834IQ5zHNIpaw== X-Received: by 2002:a1c:238e:: with SMTP id j136mr5558615wmj.33.1582639482655; Tue, 25 Feb 2020 06:04:42 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:41 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 01/12] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Date: Tue, 25 Feb 2020 14:04:26 +0000 Message-Id: <20200225140437.20609-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32d 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" Our current QAPI doc-comment markup allows section headers (introduced with a leading '=' or '==') anywhere in any documentation comment. This works for texinfo because the texi generator simply prints a texinfo heading directive at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. New section headings in the middle of the documentation of a command or event would be pretty nonsensical, and in fact we only ever output new headings using 'freeform' doc comment blocks whose only content is the single line of the heading, with two exceptions, which are in the introductory freeform-doc-block at the top of qapi/qapi-schema.json. Split that doc-comment up so that the heading lines are in their own doc-comment. This will allow us to tighten the specification to insist that heading lines are always standalone, rather than requiring the rST document generator to look at every line in a doc comment block and handle headings in odd places. This change makes no difference to the generated texi. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index fe980ce4370..ff5aea59451 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -1,7 +1,9 @@ # -*- Mode: Python -*- ## # = Introduction -# +## + +## # This document describes all commands currently supported by QMP. # # Most of the time their usage is exactly the same as in the user Monitor, this @@ -25,9 +27,13 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# +## + +## # = Stability Considerations -# +## + +## # The current QMP command set (described in this file) may be useful for a # number of use cases, however it's limited and several commands have bad # defined semantics, specially with regard to command completion. From patchwork Tue Feb 25 14:04:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403965 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 538B8930 for ; Tue, 25 Feb 2020 14:17:35 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 28FCB20732 for ; Tue, 25 Feb 2020 14:17:35 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="AAOev4/k" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 28FCB20732 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57646 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6b1i-0002bv-BZ for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:17:34 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44752) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apN-0006e6-Ga for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apJ-0005Gx-Mz for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:49 -0500 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:37985) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apJ-0005Ge-Go for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:45 -0500 Received: by mail-wr1-x442.google.com with SMTP id e8so14887088wrm.5 for ; Tue, 25 Feb 2020 06:04:45 -0800 (PST) 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=rbxvM6zBsEyzHKe8nAvY0XhamX4FQe6hP23LCjFR3Y0=; b=AAOev4/kVlRSlw0bl6cT+8Yfxz7LU8jZgbfr2JV6Iut2/gk4JMxnQ9c47D03f1sWHT 1nsdlgaBxsR4J4wQ2IjtTuxPJcBXMFZWHDyOZt9zTgYVfYpeRITrWwIky6BHE3EIKgJB ef7EI7922kGtZAGnNgNBQgSf/1dMya7gE8nkNTKhv3l/IFnj3v6Z0UaDC6kJPuMTCMlg 7VjI/1x7nxLrePNffnGEhs5MWw4R58P7aVuv7aOHCDUfjFNt62BP2F8P3MHxoA3O+Tny +j2PvCfHgc8Ep8jiUmZF7n2oMhw2aGSFlTX7fbBIXSrlu4FUFpGFQL5O+S8Bqvirzh4e P6tw== 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=rbxvM6zBsEyzHKe8nAvY0XhamX4FQe6hP23LCjFR3Y0=; b=mCHXkENQ6VuC3i+8mtvLNYnzopU0y6EZ/KYXD2Rbsahf7ZH7RT1Aub4wSmhxDPX3GP T8s34YCYD84QiMh+MdEYJIXymGqwVn8oXpRQ/7rFTL51al8JTqR4nLy+gLGq5DMBjNIM cbNDKop6pMEAnDctEuzuk6iMNYD8NQId3gbRYYw5M5IDTNNyxwapJQKpxB5DzinocKFQ 5VAaw22lAeJ/rGyyPrUxtTrJqow1UAKw/kEcYrfJ14m+bvJkRw/WOZ6JtJB2A4GEstFP bZJKEKIrKE+E3nxBIQwOdSOQbm8DGIEYzN8Xioaiyo0sqDDP0tbmaW3wcNLb06S6dCdu ghDw== X-Gm-Message-State: APjAAAXFjVTVpof92W1Ni8VULTxY+WQObE2v1UyMzL/NjM8WxIie56hq tF2Mmz1YtMLH0FXYMx27v3RYb8dPTHI7Ow== X-Google-Smtp-Source: APXvYqzJcwNKu42Ndh+7aXgzgCoNaqLPhRXzRokZRzhvTpxeHssu67rsdqASwSo3bkkalYiB8D1KBw== X-Received: by 2002:a05:6000:188:: with SMTP id p8mr72207833wrx.336.1582639484162; Tue, 25 Feb 2020 06:04:44 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.42 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:43 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 02/12] qapi/machine.json: Escape a literal '*' in doc comment Date: Tue, 25 Feb 2020 14:04:27 +0000 Message-Id: <20200225140437.20609-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::442 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/machine.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/machine.json b/qapi/machine.json index 6c11e3cf3a4..58580602524 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -12,7 +12,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 Tue Feb 25 14:04:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403923 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 52CFF1395 for ; Tue, 25 Feb 2020 14:05:37 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 293D220578 for ; Tue, 25 Feb 2020 14:05:37 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="DYGd84j9" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 293D220578 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57072 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6aq8-0007zt-C9 for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:05:36 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44768) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apP-0006f5-Iv for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:55 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apL-0005HT-ON for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:51 -0500 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]:39020) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apL-0005HE-I7 for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:47 -0500 Received: by mail-wr1-x42e.google.com with SMTP id y17so6065577wrn.6 for ; Tue, 25 Feb 2020 06:04:47 -0800 (PST) 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=nWSMAlzi0oMRfWAEf8TA2pk4lWoUJVNUT6Q1IhJAJTw=; b=DYGd84j9TBG5oKX7JWteQ/J52Juw6m8eKvyHB0IIj/AkOWjqaBLRTtjzi1YjrfG+pG /U6+JltS6Ra4W/qtwqeOnVQ8zIKvFjrInjzwjdiD5jBsdTuQ5SbmqE+N5eyiH6VY3Lfg 2fEq7///r3Zc3w0uvHb+NTfl+C31VbmhK+bdXdwkNoiLunBlXbJZISQb+Gh/J7/iiVOx X+E8jonWpyI48BACpLYbYT/HThtJu2lrTCVRHTSo/XtO9jJ8r7B39y1rZgnELB1AjtDL M8HoTaIdSNWjct7Yy1xO/UjMI6pdkrWf02trbiQ5TrzM1wJuddvxHXkjtMfxbf0j1Zh0 sAEw== 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=nWSMAlzi0oMRfWAEf8TA2pk4lWoUJVNUT6Q1IhJAJTw=; b=F1ywz1KBYVMyGW9z4OYefNxkSbIrXOjWaxEExUZvAH367wUL1hpSnwuvc8Q1jYQI6H 0EbtaLYRRMcrY4AO5yPTkTRsnXB6GbE1FPrEu/3wiqyYBU+PEAzbibiji5rzv1uJk1h6 3fudnvCdaSjlCW/OW3nFZ6nU3jQYJnFtPP2MLIxD3+ejMbZTtnx3BYWALd1cgtR/nKqQ hjIG/4XKmCiL3ES/rVNKNX8YnXCDIT67b/rELRW4O5k4H0WEpLZQz4XlIQwLU4vifvWP zjS+4bsW/MWxtdfErKleU+gQgYb3O5DxvD72ssI3UQp/KWDyLzSier4nJ7vQwlaIW45a MRBg== X-Gm-Message-State: APjAAAUiwmThIMglLpuct4mnudhaacTTOUWbyh79pBkUxkFe0RjIGsyB nQ2oYe/mOpWQ0cqA4gGtMuV8eShQamF1fA== X-Google-Smtp-Source: APXvYqx8zlC45YD0O5JzwN0FOrY/TA0+n2C+HeIozGSQzHYHLrLSGOvpsi7usMOiXpOzhDOTQKztVw== X-Received: by 2002:a5d:488c:: with SMTP id g12mr70004481wrq.67.1582639486142; Tue, 25 Feb 2020 06:04:46 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:44 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 03/12] tests/qapi/doc-good.json: Clean up markup Date: Tue, 25 Feb 2020 14:04:28 +0000 Message-Id: <20200225140437.20609-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42e 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" doc-good.json tests some oddities of markup that we don't want to accept. Make them match the more restrictive rST syntax: * in a single list the bullet types must all match * lists must have leading and following blank lines * indentation is important * 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. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- New patch in v2 --- 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 d992e713d97..a45dc22848c 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -10,25 +10,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 @@ -62,7 +62,7 @@ ## # @Base: # @base1: -# the first member +# the first member ## { 'struct': 'Base', 'data': { 'base1': 'Enum' } } @@ -101,7 +101,7 @@ ## # @Alternate: # @i: an integer -# @b is undocumented +# @b is undocumented ## { 'alternate': 'Alternate', 'data': { 'i': 'int', 'b': 'bool' } } @@ -115,7 +115,7 @@ # @arg1: the first argument # # @arg2: the second -# argument +# argument # # Features: # @cmd-feat1: a feature @@ -124,6 +124,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 4c9406a464d..9503a3a3178 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -68,25 +68,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 d4b15dabf03..1e8063c8579 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 Tue Feb 25 14:04:29 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403967 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5CC48930 for ; Tue, 25 Feb 2020 14:18:52 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id E1F0020732 for ; Tue, 25 Feb 2020 14:18:51 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="gEbxMrgF" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E1F0020732 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57670 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6b2w-0003db-Sy for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:18:50 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44780) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apU-0006gq-2A for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:00 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apN-0005Hy-Ch for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:53 -0500 Received: from mail-wm1-x332.google.com ([2a00:1450:4864:20::332]:36899) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apN-0005Hm-6S for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:49 -0500 Received: by mail-wm1-x332.google.com with SMTP id a6so3274936wme.2 for ; Tue, 25 Feb 2020 06:04:49 -0800 (PST) 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=wpXd5QxscHZ5Ze+pVlbaJlNdMe0Q3RlgSzZJLeNwcSk=; b=gEbxMrgFpMlpITus6cj+2ufTiZDBHcGYIKAg1pcNjZcLGcvuVWH81XG80AoOzvyvDQ /qOy34WabQWnTWKBDGYTFn2NDiFUGV7Cwm9bM7/jIo5Cvx//vGW390Kbx+GZtZKCUNSw XzBsvcWoPPXli0a6yRW3lrnXYJdxBSQGhRJpIHlN4cJB4cEnRbn02x1zPmMqPxGEb1AU 2D2ngZpL3OM/BJXQ/Rmnk6oQD6dUPxc4A0lVB9IzhQfF3FLJyJi+qB+DnaP5Xfzm0yeg NExSu6eHgk4aIFFT83CpehgK8DH9rxVMLqPg1xVBqkRKM4UVDxzGQ46YjqVGZDGMz/92 D4cg== 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=wpXd5QxscHZ5Ze+pVlbaJlNdMe0Q3RlgSzZJLeNwcSk=; b=Zmu+D1djlZ+GXN7UKL6GXsnA0feKcuM/q051KHBVWc2VNNEHBZMaKtxBtDohZyVHCz PotrTpA8NQyIoZEOpj6OMVkWUnS7+I3kb3txHkdajInsffkCfMyErRKK89EuPchF9oDo +EzS8ATFJzJwCMbRQ6dVJVE0gXrnxJpnbS1xwlbtydtvX8zAEOAcKwVJKaEUGNSHuvMY dMs3cbLTwd7zYjLYa/bESVdINAz2IoarcfvosGya2+hLHsIIPd6/wdjB6tfj/DPbYGIE FRRZuNjiOKdF6ghOPbZUvzP40SFPuP2A+Y39PSmguiBJRzYTVAWsLnhflcloMYvo4n1l 7Kug== X-Gm-Message-State: APjAAAUt0mnsSamRjK7DIkjxBRJkWxrpui220bt8bJwBTZM2ykRBfbTH ET6GcnEmJViasqbIV41GVxuMjoM89rxvIw== X-Google-Smtp-Source: APXvYqy2g453uZkhifYJl9lv/maYuAsHoBM6tmHvyuQnmo4KYw4D3/Td4y8ySBOU19q9wWE3WhY8AQ== X-Received: by 2002:a7b:cc97:: with SMTP id p23mr5489064wma.89.1582639487596; Tue, 25 Feb 2020 06:04:47 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:46 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 04/12] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Tue, 25 Feb 2020 14:04:29 +0000 Message-Id: <20200225140437.20609-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::332 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- New in v2: update doc-good.out as noted in final para of commit msg --- 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 1787a53d91a..26cd1a1751e 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 342792e4103..2196ec5de1e 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -422,10 +422,10 @@ class QAPIDoc(object): 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): """ @@ -458,7 +458,7 @@ class QAPIDoc(object): 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] @@ -477,7 +477,7 @@ class QAPIDoc(object): self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_various_line(self, line): """ @@ -500,10 +500,6 @@ class QAPIDoc(object): 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 9503a3a3178..a65bce639ff 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -71,20 +71,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 @@ -144,7 +144,7 @@ doc symbol=Alternate arg=i an integer -@b is undocumented + @b is undocumented arg=b doc freeform @@ -157,7 +157,7 @@ doc symbol=cmd the first argument arg=arg2 the second -argument + argument arg=arg3 feature=cmd-feat1 From patchwork Tue Feb 25 14:04:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403969 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id B3E2613A4 for ; Tue, 25 Feb 2020 14:19:48 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 8A9B720732 for ; Tue, 25 Feb 2020 14:19:48 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="aL0IevAW" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 8A9B720732 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57682 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6b3r-0004WU-PY for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:19:47 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44778) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apT-0006ga-TB for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:00 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apO-0005IR-Qt for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:55 -0500 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:50909) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apO-0005IC-KD for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:50 -0500 Received: by mail-wm1-x32f.google.com with SMTP id a5so3133530wmb.0 for ; Tue, 25 Feb 2020 06:04:50 -0800 (PST) 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=yx82A80BgFchuY4arBJB9y5p01nca9y/eUUsgMiGXgw=; b=aL0IevAW73/+IgMxhYgXFw0v2Vjx2sx5oRUNPfkyQUqmGgHl6fo7D7eKK+wS2w9lVL ASnIbXoEyR7jbAAImZotxCXC9xV1TQ3IUANkbtzkStmR+PecdGh09X/9aU3XXILjaRUr o7kDxVcYsAJJc31u7Ck8S+C72p16dBmHz/fHFo2JQ72r1aiY6G14otq3bFTM02jRN6hc qzHClxCoMR1jmkvnxWnDxN5/vrvRxvxIuMOysI4XoGMQXTOVHHSSvZqoIhIzLRO+lqYA 6+0lJbZ2fo8Dsev+Un8NhaDO0XKjtr3KZXlEe5+T4QylY+fHQGuBArgUHOjQdk6u8eb1 kcmw== 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=yx82A80BgFchuY4arBJB9y5p01nca9y/eUUsgMiGXgw=; b=PjN720ppxQfSR5nAIpNNiMrzMFmxmiFDIW8WgkXw59uteTrLWLDpG2T/Gg+MAlYAzx Cl5mRFBITDfnMyLGLOZclRpMbwWfECmJafkOUf437L7kXeZyhWL1KkaLl0L3w/fGt/rx OvFDznFljR0YVWrOU42KKEkpEgZPVJjktCVjoS5V5c8lPW2cBre3EtLI/8s325xpg4iJ hqyEe9ntoM51vl9/RsGJ4kZwMLI3IGvJCujpohM9Js2oGGmRiW5NlAlzg11JOXW3lvbN dsZYxtU1gJx2kaqf2KrAX2BpaFsdD7wz1CbaVNMDKZEam/DlY9F3DSKEkZMaZnweMQv4 TffQ== X-Gm-Message-State: APjAAAVvGTdqSFE/SyocYbIYVK1u25fMdeKWd6R+rb0W6L8KgoQR3C5U 6BwcHgQt1HvbW+pHibAEK9R6C5GIcNxJUA== X-Google-Smtp-Source: APXvYqwR2DqYZdTbKJJ8oF2NeK/aHwTnYWK9g7ToPHH7pQus/W8ZMTPWYkUoA0RY+up52JrQ9J73vg== X-Received: by 2002:a7b:cbcf:: with SMTP id n15mr5477846wmi.21.1582639489044; Tue, 25 Feb 2020 06:04:49 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:48 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 05/12] scripts/qapi/parser.py: improve doc comment indent handling Date: Tue, 25 Feb 2020 14:04:30 +0000 Message-Id: <20200225140437.20609-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32f 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. The exception is that we always retain indentation as-is for Examples sections, because these are literal text. 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. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- v1->v2: Update doc-good.out as per final para. --- scripts/qapi/parser.py | 82 +++++++++++++++++++++++++++------- tests/qapi-schema/doc-good.out | 4 +- 2 files changed, 67 insertions(+), 19 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 2196ec5de1e..66f802641c9 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -313,18 +313,32 @@ class QAPIDoc(object): """ class Section(object): - 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 # the list of lines for this section 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: + spacecount = len(line) - len(line.lstrip(" ")) + if spacecount > self._indent: + spacecount = self._indent + if spacecount < self._indent: + raise QAPIParseError(self._parser, "unexpected de-indent") + line = line[spacecount:] + self.text += line.rstrip() + '\n' class ArgSection(Section): - def __init__(self, name): - QAPIDoc.Section.__init__(self, name) + def __init__(self, parser, name, indent=0): + QAPIDoc.Section.__init__(self, parser, name, indent) self.member = None def connect(self, member): @@ -338,7 +352,7 @@ class QAPIDoc(object): 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() @@ -443,7 +457,18 @@ class QAPIDoc(object): if name.startswith('@') and name.endswith(':'): line = line[len(name)+1:] - self._start_args_section(name[1:-1]) + if not line or line.isspace(): + # Line was just the "@arg:" header; following lines + # are not indented + indent = 0 + line = '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 1, and we + # pad out this first line so it is handled the same way + indent = len(name) + 1 + 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) @@ -465,7 +490,17 @@ class QAPIDoc(object): if name.startswith('@') and name.endswith(':'): line = line[len(name)+1:] - self._start_features_section(name[1:-1]) + if not line or line.isspace(): + # Line is just the "@name:" header, no ident for following lines + indent = 0 + line = '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 3, and we + # pad out this first line so it is handled the same way + indent = len(name) + 1 + 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) @@ -498,11 +533,23 @@ class QAPIDoc(object): % (name, self.sections[0].name)) elif self._is_section_tag(name): line = line[len(name)+1:] - self._start_section(name[:-1]) + if not line or line.isspace(): + # Line is just "SectionName:", no indent for following lines + indent = 0 + line = '' + elif name.startswith("Example"): + # The "Examples" section is literal-text, so preserve + # all the indentation as-is + indent = 0 + else: + # Line is "SectionName: some text", indent required + indent = len(name) + 1 + 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") @@ -511,21 +558,21 @@ class QAPIDoc(object): "'%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): @@ -548,7 +595,7 @@ class QAPIDoc(object): 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): @@ -556,7 +603,8 @@ class QAPIDoc(object): raise QAPISemError(feature.info, "feature '%s' lacks documentation" % feature.name) - self.features[feature.name] = QAPIDoc.ArgSection(feature.name) + self.features[feature.name] = QAPIDoc.ArgSection(self._parser, + feature.name) self.features[feature.name].connect(feature) def check_expr(self, expr): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index a65bce639ff..0302ce0bde1 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -144,7 +144,7 @@ doc symbol=Alternate arg=i an integer - @b is undocumented +@b is undocumented arg=b doc freeform @@ -157,7 +157,7 @@ doc symbol=cmd the first argument arg=arg2 the second - argument +argument arg=arg3 feature=cmd-feat1 From patchwork Tue Feb 25 14:04:31 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403927 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id CE4DC13A4 for ; Tue, 25 Feb 2020 14:07:05 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 952EF2084E for ; Tue, 25 Feb 2020 14:07:05 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="kGKHyCSE" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 952EF2084E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57114 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6arY-0002Wv-Is for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:07:04 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44836) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apZ-0006qP-4F for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:05 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apU-0005JQ-5V for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:01 -0500 Received: from mail-wr1-x432.google.com ([2a00:1450:4864:20::432]:34026) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apT-0005Ip-Rk for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:56 -0500 Received: by mail-wr1-x432.google.com with SMTP id z15so6544690wrl.1 for ; Tue, 25 Feb 2020 06:04:55 -0800 (PST) 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=aSIfJos+oHjuy71lu00dahA+zgfTJLqV1cd5BBRK4rw=; b=kGKHyCSEJbFZeEbaY5doJw7R6as5lwBPqQlIyKubMA7Z5rzbeFr1+kzY4fA6QECcL6 tjSJUfREZuGlEDq04xQC4KCLRHGdccNIhypdrraXmub7aycQNHtPPuDKV8uhCfhJdakO 0sd42dcboPSEoIFeR68dq5sOKIp2LVjTBNXDlsTP/5HYw8EWVVKBYLtKpxcrwzvQxaY/ 3T4Eg7PXsPiklyUzx7khtnNbGRtvz5nSQjlZszLXGrDxOnXI5Ky92C/vjeV4WgZ5z95S sMfKatvkvW5wNqu4bqxhJNOyDJlIVu47B9KM1LQWGTFWaLIhK/6n2NPviMhE9VtPg8ka O6HA== 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=aSIfJos+oHjuy71lu00dahA+zgfTJLqV1cd5BBRK4rw=; b=m6/XmY45W9uRUR2NcCNP5YliIqbrNuYqoxWKPD0s2y/muc3C4D4dm9KSEHVOqijlf8 JHcVpbsnLpSh0oglmZ+PbQaDp7mWoy+phmTSAfFD3U9eoT9Iafi5ESuWCxZ1jkFoLYNq 6nv3OuvCVKCO/HD89i6i7rwnTOmQKseT10cyDlAHsvsFWzkZspGMibSNYDEH25HqPm5a jH1fOCcmjdl1i5qMSjariXCpYEmpqEXnyx619OMPVSvUJDzAPJCrh/bMCItzSIQbstWk 8ZyvLDVDb2ORYiBDvBvmBHu1EL/oVf3HFVL943Afz8wcvpRw5+QbKh5a3i3g/SQTkV+Q V9zg== X-Gm-Message-State: APjAAAWuz0G2XJqHgePk+5RWU6o1zjQpbmrPuE2yRClHYj6WtCeXGLq/ +L9T7RgD4/xrD1D80K5wMpEXaMg0IRNK0w== X-Google-Smtp-Source: APXvYqwMu1o+cEqxfoNZoCumaM0K2X3Rpv+p3riSsW5I73rAOF+fPgdJ/BK5lxcVDIbbc3z1pcWA/A== X-Received: by 2002:a5d:550f:: with SMTP id b15mr14671789wrv.19.1582639490827; Tue, 25 Feb 2020 06:04:50 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:50 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 06/12] docs/sphinx: Add new qapi-doc Sphinx extension Date: Tue, 25 Feb 2020 14:04:31 +0000 Message-Id: <20200225140437.20609-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::432 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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 --- MAINTAINERS | 1 + docs/conf.py | 6 +- docs/sphinx/qapidoc.py | 504 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 510 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapidoc.py diff --git a/MAINTAINERS b/MAINTAINERS index 195dd58cac1..ea93a69611b 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2805,3 +2805,4 @@ M: Peter Maydell S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/sphinx/ diff --git a/docs/conf.py b/docs/conf.py index 7588bf192ee..1ada0b8f427 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,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 ------------------------------------------------ @@ -64,7 +67,7 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'qmp_lexer', 'hxtool'] +extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'qapidoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -232,3 +235,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..d0dd6e93d4c --- /dev/null +++ b/docs/sphinx/qapidoc.py @@ -0,0 +1,504 @@ +# 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 JSON schema files, and insert them all into the current document. +# The conf.py file must set the qapidoc_srctree config value to +# the root of the QEMU source tree. +# Each qapi-doc:: directive takes one argument which is the +# path of the .json file to process, relative to the source tree. + +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, 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): + """Like join, but for arbitrary iterables, notably arrays""" + 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 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 None + + section = self._make_section(what) + section += dlnode + return section + + def _nodes_for_enum_values(self, doc, what): + """Return 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 None + + section = self._make_section(what) + section += dlnode + return section + + def _nodes_for_arguments(self, doc, boxed_arg_type): + """Return 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 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 None + + section = self._make_section('Features') + section += dlnode + return section + + def _nodes_for_example(self, exampletext): + """Return doctree nodes for a code example snippet""" + return nodes.literal_block(exampletext, exampletext) + + def _nodes_for_sections(self, doc, ifcond): + """Return doctree nodes for additional sections following arguments""" + 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) + if ifcond: + snode = self._make_section('If') + snode += self._nodes_for_ifcond(ifcond, with_if=False) + nodelist.append(snode) + if not nodelist: + return None + 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, members, prefix): + doc = self._cur_doc + self._add_doc('Enum', + [self._nodes_for_enum_values(doc, 'Values'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_object_type(self, name, info, ifcond, base, members, variants, + features): + 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, ifcond)]) + + def visit_alternate_type(self, name, info, ifcond, 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, ifcond)]) + + def visit_command(self, name, info, ifcond, arg_type, ret_type, gen, + success_response, boxed, allow_oob, allow_preconfig, + features): + 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, ifcond)]) + + def visit_event(self, name, info, ifcond, 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, 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: + self._serror('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). + + As a special case, if the freeform document is a single line + of the form '= Heading text' it is treated as 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 + + if re.match(r'=+ ', doc.body.text): + # Section or subsection heading: must be the only thing in the block + (heading, _, rest) = doc.body.text.partition('\n') + if rest != '': + raise ExtensionError('%s line %s: section or subsection heading' + ' must be in its own doc comment block' + % (doc.info.fname, doc.info.line)) + (leader, _, heading) = heading.partition(' ') + self._start_new_heading(heading, len(leader)) + return + + node = self._make_section(None) + self._parse_text_into_node(doc.body.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) + 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 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] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(qapifile)) + + try: + schema = QAPISchema(qapifile) + except QAPIError as err: + # Launder QAPI parse errors into Sphinx extension errors + # so they are displayed nicely to the user + raise ExtensionError(str(err)) + + 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() + + 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 + ) From patchwork Tue Feb 25 14:04:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403929 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9CD3D1395 for ; Tue, 25 Feb 2020 14:07:42 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 6396921744 for ; Tue, 25 Feb 2020 14:07:42 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="wDLlX9Up" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 6396921744 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57124 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6as9-0003bu-FD for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:07:41 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44838) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apZ-0006qT-5f for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:05 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apU-0005Jf-DO for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:01 -0500 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]:35925) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apU-0005Ir-6O for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:56 -0500 Received: by mail-wm1-x32a.google.com with SMTP id p17so3285141wma.1 for ; Tue, 25 Feb 2020 06:04:56 -0800 (PST) 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=h8KcToOpNdvd1jAEU1XTyzSES2UTXwJrY4z+tY0Zjnk=; b=wDLlX9Up0gY5JX32oABoOtiNrnL/AN7dlHcI9lmmJ7P+WZqYD0RcwQhig7NKmkh5Kw BkZ564/B8+Ef77/uwxQdTdtLnFrW++SIJWIoYm0P63AWD8J6NPcpAF+WQ9yAcPCbjaH7 uod5DjDIobZf9YgM8s/TgOBiZ7KMipolNXO+VmrrgI4dvPNGA1Bj/80BkM1sFc0HwsTR 9urXcnYJ0yz2DCB5G0KyQGVfxeqqVoao+UM+xD2VqDpDTz6Z84Lr5UmNMYXCtBqTIl8C FSsbt6mVFBATx2qvcI8jkcmyOnCVvnW82hqQbwL3yfCddwKVg7RSo8mBbZgJT6+51iD6 debw== 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=h8KcToOpNdvd1jAEU1XTyzSES2UTXwJrY4z+tY0Zjnk=; b=U+Jls0yJaY7xP7vqZ2xIrB6F2YTR1CnE86SH+Pz2xz6HRf346UQTIBFFuyf01uqCOE 0hxJmkR0+V4EMFNqmKC/i3QbazZD1kZMA7MsDIOteyhBVNDtOFoX4EzReyEbOTLoVpqS uA/Zp1P8sMV8FISKDIB3n3y2+YEQlbTumbgBMY+0SPsPJFFQ/ceBVChWK/40Jk86vXZw toA4V0yCaaj7UOfavzCvwW4QELJuB18W3s6D6TmHZdBFp6P8di4nRAxSYJkrdnMWtDux bEKS0kzSviFpPXDPIdJyq4J+hYDz73DutdOvtB1yYjYTLQ3SgDVDuD1YLUm4sm+v94EC 9u/g== X-Gm-Message-State: APjAAAVgXwmRXTTKVfOnRUXFPp2isQ8IN2z92I/p7uhpfhhr9Qf444ul cRfdctUYXa9I5iGBohcLrslB2RATNOeB6g== X-Google-Smtp-Source: APXvYqzqpbwfLgvYjmgpSnDz3pvv/oFhrPXj05PaJp/Ab+sjmiy0MRtB+Pn9hJbVDP6OOzod78CdVw== X-Received: by 2002:a05:600c:218b:: with SMTP id e11mr5639680wme.56.1582639492270; Tue, 25 Feb 2020 06:04:52 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:51 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 07/12] docs/interop: Convert qemu-ga-ref to rST Date: Tue, 25 Feb 2020 14:04:32 +0000 Message-Id: <20200225140437.20609-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32a 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. Signed-off-by: Peter Maydell --- Makefile | 41 ++++++++---------- MAINTAINERS | 2 +- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-ga-ref.rst | 4 ++ docs/interop/qemu-ga-ref.texi | 80 ----------------------------------- 7 files changed, 25 insertions(+), 106 deletions(-) create mode 100644 docs/interop/qemu-ga-ref.rst delete mode 100644 docs/interop/qemu-ga-ref.texi diff --git a/Makefile b/Makefile index aa9cc0b5847..bdda1232b27 100644 --- a/Makefile +++ b/Makefile @@ -353,7 +353,7 @@ DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7 -DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7 +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 DOCS+=docs/qemu-cpu-models.7 DOCS+=$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS @@ -775,11 +775,11 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-ga-qapi.texi docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 docs/interop/qemu-ga-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html + rm -f docs/interop/qemu-qmp-qapi.texi + rm -f docs/interop/qemu-qmp-ref.7 + rm -f docs/interop/qemu-qmp-ref.txt + rm -f docs/interop/qemu-qmp-ref.pdf + rm -f docs/interop/qemu-qmp-ref.html rm -f docs/qemu-cpu-models.7 rm -rf .doctrees $(call clean-manual,devel) @@ -834,7 +834,7 @@ endif # and also any sphinx-built manpages. define install-manual = for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done endef # Note that we deliberately do not install the "devel" manual: it is @@ -870,9 +870,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP endif ifneq (,$(findstring qemu-ga,$(TOOLS))) $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" endif endif ifdef CONFIG_VIRTFS @@ -1062,7 +1060,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) $(call build-manual,interop,html) $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1074,7 +1072,10 @@ $(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system) $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/docs/qemu-option-trace.rst.inc $(call build-manual,tools,html) -$(call define-manpage-rule,interop,qemu-ga.8) +$(call define-manpage-rule,interop,\ + qemu-ga.8 qemu-ga-ref.7,\ + $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ + $(qapi-py)) $(call define-manpage-rule,system,qemu-block-drivers.7) @@ -1100,17 +1101,14 @@ qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxt docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ -docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi - @cp -p $< $@ - qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi qemu.1: qemu-option-trace.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs -info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info -pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf -txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt +html: qemu-doc.html docs/interop/qemu-qmp-ref.html sphinxdocs +info: qemu-doc.info docs/interop/qemu-qmp-ref.info +pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf +txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-options.texi \ @@ -1119,11 +1117,6 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-monitor-info.texi \ docs/qemu-cpu-models.texi docs/security.texi -docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ - docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \ - docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7: \ - docs/interop/qemu-ga-ref.texi docs/interop/qemu-ga-qapi.texi - docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ diff --git a/MAINTAINERS b/MAINTAINERS index ea93a69611b..2bf8744a9ea 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2137,9 +2137,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/docs/index.html.in b/docs/index.html.in index cf61b1cf448..ce10ce55a23 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -9,7 +9,6 @@
  • User Documentation
  • QMP Reference Manual
    • -
  • Guest Agent Protocol Reference
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
  • System Emulation User's Guide
    • 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 049387ac6de..f3af38dce17 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,5 +18,6 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-ga-ref vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst new file mode 100644 index 00000000000..013eac0bb53 --- /dev/null +++ b/docs/interop/qemu-ga-ref.rst @@ -0,0 +1,4 @@ +QEMU Guest Agent Protocol Reference +=================================== + +.. 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 ddb76ce1c2a..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 qemu-ga-qapi.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 From patchwork Tue Feb 25 14:04:33 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403955 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0835213A4 for ; Tue, 25 Feb 2020 14:13:55 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id C3BCF21927 for ; Tue, 25 Feb 2020 14:13:54 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="j8o/Z/Ql" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org C3BCF21927 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57474 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6ay7-0007Fs-TD for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:13:51 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44875) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apb-0006uD-AF for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:08 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apU-0005Jv-VC for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:03 -0500 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:45036) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apU-0005J1-NK for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:56 -0500 Received: by mail-wr1-x42c.google.com with SMTP id m16so14840790wrx.11 for ; Tue, 25 Feb 2020 06:04:56 -0800 (PST) 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=bcNSVMaYJhZkdDosvs+LSraOwfJZoWt9LT57DcPqGpc=; b=j8o/Z/QlevYeBg/wkXAXk3ifrwaHcDTKIoLhoPLWVgbzthCZU4pDVj/Xl2vWC7ohPA bRmvIg6jBGrtSJKugyYPCNLC4RB0vTiqedjXyizt+xKo0CXhGHJrfxlEJakJDTFgejxC IRR3dVy7Oi7ttPfa6U/LVQL3NKeRdyXSGAn74BrGNacjk0y4rn5n0qVyumEqG7bC4o6X 2+4vlp+ZDv2AcL/eYWhqIJkAK9iVopExle8VbiOm7+UvSPltg5liffTwAsGH3y4xzYDe j8N+OLixMopLsAMSeyBIM2Gx79ngIS10K1RPKysgvk6HLy4rHFdK44Z5XLDSDowm1+u7 gwqQ== 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=bcNSVMaYJhZkdDosvs+LSraOwfJZoWt9LT57DcPqGpc=; b=CnHUxollKDdZ+ofF4i9M1zoMwFACxjXAcs5Rms4bgCHuA1gW4ODA1gVeZjKN3H0MCu oeECcUuJQ3E+qNpfNZiw5M3KVBiSHE46v/LxXXnYtjISqySzubUizicF22BTbKk3+POr X4IjT4v/mBBbGBXC2mf4wsqLgcIMXn/8r5SMcaEFy0kuoHRpL8U7GNk0SbaAX9e952zI gDq1BBUjMYLMoKrzRjYMNDYFw9yk6lEjzQC073FTgyJTTJ1nz3LUKVgCzyyr25g66CxT HoFI4pp3JZLq98As9dMJLaugGYmG4ugZFWzjshnTPWa1o1IXtuj/eCpEFfrA3S/RwI0K Nd/A== X-Gm-Message-State: APjAAAXllvzwVHcb8U3DO9uTWh3zckAf918glppv1GfysdZTjEpwIN9Z FMF2RwGAM5yX7hi63DNR4bz+PQmZFkCORA== X-Google-Smtp-Source: APXvYqz4uonVc/xRlZTDm8tTHPcplWjWYjihr3zOSB+x7xF2Wkq2ND4/7jpC+UKACdlDrmbrMs1DsA== X-Received: by 2002:adf:e550:: with SMTP id z16mr75280292wrm.5.1582639493809; Tue, 25 Feb 2020 06:04:53 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:53 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 08/12] docs/interop: Convert qemu-qmp-ref to rST Date: Tue, 25 Feb 2020 14:04:33 +0000 Message-Id: <20200225140437.20609-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42c 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. Signed-off-by: Peter Maydell --- Makefile | 39 +++++------------ docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-qmp-ref.rst | 4 ++ docs/interop/qemu-qmp-ref.texi | 80 ---------------------------------- 6 files changed, 18 insertions(+), 109 deletions(-) create mode 100644 docs/interop/qemu-qmp-ref.rst delete mode 100644 docs/interop/qemu-qmp-ref.texi diff --git a/Makefile b/Makefile index bdda1232b27..f6e7f500416 100644 --- a/Makefile +++ b/Makefile @@ -126,7 +126,6 @@ GENERATED_QAPI_FILES += qapi/qapi-events.h qapi/qapi-events.c GENERATED_QAPI_FILES += $(QAPI_MODULES:%=qapi/qapi-events-%.h) GENERATED_QAPI_FILES += $(QAPI_MODULES:%=qapi/qapi-events-%.c) GENERATED_QAPI_FILES += qapi/qapi-introspect.c qapi/qapi-introspect.h -GENERATED_QAPI_FILES += qapi/qapi-doc.texi generated-files-y += $(GENERATED_QAPI_FILES) @@ -352,8 +351,8 @@ ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_NG),yyy) DOCS+=$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 -DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7 DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-qmp-ref.7 DOCS+=docs/qemu-cpu-models.7 DOCS+=$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS @@ -628,8 +627,7 @@ $(SRC_PATH)/scripts/qapi-gen.py qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h \ qga/qapi-generated/qga-qapi-visit.c qga/qapi-generated/qga-qapi-visit.h \ qga/qapi-generated/qga-qapi-commands.h qga/qapi-generated/qga-qapi-commands.c \ -qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-init-commands.c \ -qga/qapi-generated/qga-qapi-doc.texi: \ +qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-init-commands.c: \ qga/qapi-generated/qapi-gen-timestamp ; qga/qapi-generated/qapi-gen-timestamp: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ @@ -775,11 +773,6 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html rm -f docs/qemu-cpu-models.7 rm -rf .doctrees $(call clean-manual,devel) @@ -834,7 +827,7 @@ endif # and also any sphinx-built manpages. define install-manual = for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' -name '*.[0-9]'); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done endef # Note that we deliberately do not install the "devel" manual: it is @@ -851,13 +844,11 @@ install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)" ifdef CONFIG_POSIX $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7" $(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7" ifeq ($(CONFIG_TOOLS),y) @@ -1060,7 +1051,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qga/qapi-schema.json $(qapi-modules) $(qapi-py) $(call build-manual,interop,html) $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1073,9 +1064,9 @@ $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-deps,tools) $(SRC_PATH)/qemu- $(call build-manual,tools,html) $(call define-manpage-rule,interop,\ - qemu-ga.8 qemu-ga-ref.7,\ + qemu-ga.8 qemu-ga-ref.7 qemu-qmp-ref.7,\ $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ - $(qapi-py)) + $(qapi-modules) $(qapi-py)) $(call define-manpage-rule,system,qemu-block-drivers.7) @@ -1098,17 +1089,14 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/scripts/hxtool qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxtool $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") -docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi - @cp -p $< $@ - qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi qemu.1: qemu-option-trace.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi -html: qemu-doc.html docs/interop/qemu-qmp-ref.html sphinxdocs -info: qemu-doc.info docs/interop/qemu-qmp-ref.info -pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf -txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt +html: qemu-doc.html sphinxdocs +info: qemu-doc.info +pdf: qemu-doc.pdf +txt: qemu-doc.txt qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-options.texi \ @@ -1117,11 +1105,6 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-monitor-info.texi \ docs/qemu-cpu-models.texi docs/security.texi -docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ - docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ - docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ - docs/interop/qemu-qmp-ref.texi docs/interop/qemu-qmp-qapi.texi - $(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl # Reports/Analysis diff --git a/docs/index.html.in b/docs/index.html.in index ce10ce55a23..ca321368be0 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -8,7 +8,6 @@

    QEMU @@VERSION@@ Documentation

    • User Documentation
      • -
    • QMP Reference Manual
    • System Emulation Management and Interoperability Guide
    • System Emulation Guest Hardware Specifications
    • System Emulation User's Guide
      • 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 f3af38dce17..2cd97c6ff42 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -19,5 +19,6 @@ Contents: pr-helper qemu-ga qemu-ga-ref + qemu-qmp-ref vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst new file mode 100644 index 00000000000..e640903abaf --- /dev/null +++ b/docs/interop/qemu-qmp-ref.rst @@ -0,0 +1,4 @@ +QEMU QMP Reference Manual +========================= + +.. 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 bb25758bd02..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 qemu-qmp-qapi.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 From patchwork Tue Feb 25 14:04:34 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403971 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 8776314BC for ; Tue, 25 Feb 2020 14:20:48 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 5B35A2084E for ; Tue, 25 Feb 2020 14:20:48 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="w79gtH5S" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 5B35A2084E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57706 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6b4p-0005WR-K1 for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:20:47 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44834) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apY-0006q1-U9 for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:04 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apV-0005K3-3D for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:00 -0500 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:41336) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apU-0005JZ-Te for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:57 -0500 Received: by mail-wr1-x436.google.com with SMTP id v4so2012872wrs.8 for ; Tue, 25 Feb 2020 06:04:56 -0800 (PST) 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=MdwVWEG8hNJRFTkFaf2CNe1RBfSUpiMOo7qqDUbXW8o=; b=w79gtH5SNijde6DCZVIBA8S5/L2vGg1f+cTC4KRGN09Z6/EdTn2Skd1y3jA4rTwODi 2gmJwraalL0NlybFYJsxCSJz0p8JekbD+3lyLBfhz+S6MkZku//jv5QNg+/fPHgbi37G zoyZw/OFczQCrTaTVApJoH4ZrxwwU7ugfs7DhD0sqlcuAa+FwMRgbLmgUUTPXo3d+zBI hlDknMOzoXHin/ONTStqtNGRshSYfo/GE68KyrK8JPYD76L22SLoaw8bJwa+YSEoDlWU osZST5EAWs1/KA4dgazdDHL6jS0VJzMmgZekcItNaO1Cyrc94TOEzGlK/Ki1zv9DmIfs L3iw== 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=MdwVWEG8hNJRFTkFaf2CNe1RBfSUpiMOo7qqDUbXW8o=; b=I/eShAVbJ7ih5uUdLsdePoeqOhT0g+G7boqUI4C3yKurFKyL2zhvKO+P/k259ENpr7 xOTnZ17GlF8AmIE0Suu7ZcF0b7/FXYyR1lrvVk2l4Q62nl+oZN3Lo2nZ+vM/apijcq72 Vb3b1UGRxUzgKQ0LnTeQpiW+Q7g66cVVRrF3wsMTdPO6qaRwJ5xY6HNM7eS1T7sZnnmC 02eTShCyeGIZIQvKQd9xGBEvJgOpA0SyestHgjMrtpltxL99FY4fokVGBzkYb8YhuJ3i 4oSC77eRtHeTMWxIYGx20eUw5OnwxP5CnAbaPHZLNwINd9/xixtoWsoDpxM5AWyY6tUB H8cQ== X-Gm-Message-State: APjAAAURXrK1q/vDzZpn0GYE+MkR7BrYJ+YtKDGsbq6EJwoquJsxjY4H PYva0C+6rJkaA8uK4gwiapE7DOQmBIxiPg== X-Google-Smtp-Source: APXvYqxItp8SlDevQ5svz2yGlP0xIuFCG+gE6T1dwfz1l4zhDDY3xkvh2cWHRDAITjtZTkjrohLNIw== X-Received: by 2002:adf:9486:: with SMTP id 6mr14586521wrr.341.1582639495587; Tue, 25 Feb 2020 06:04:55 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.54 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:54 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 09/12] qapi: Use rST markup for literal blocks Date: Tue, 25 Feb 2020 14:04:34 +0000 Message-Id: <20200225140437.20609-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::436 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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.) 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 85e27bb61f4..0c9c21927f9 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -550,13 +550,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 ff5aea59451..440fece703f 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -22,8 +22,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 Tue Feb 25 14:04:35 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403949 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5B65D1395 for ; Tue, 25 Feb 2020 14:09:29 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 31CD021744 for ; Tue, 25 Feb 2020 14:09:29 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="A9okzY0Z" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 31CD021744 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57198 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6ats-00078D-Cf for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:09:28 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44851) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6apa-0006sL-8x for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apW-0005KP-Bs for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:02 -0500 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:41679) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apW-0005KA-4q for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:04:58 -0500 Received: by mail-wr1-x442.google.com with SMTP id v4so2012959wrs.8 for ; Tue, 25 Feb 2020 06:04:58 -0800 (PST) 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=ct264XXsXB4Yfv0geBlQAhYKTLlUfdyjxR0wyex+U9E=; b=A9okzY0Z0810WgmCdZy9+pPunrM2gq7VOkPqeMwQiN1H8OxYZitFfR1fyA55UkaBAG MDZ/gndSJr2y3eATJOZlNyR2KXAGRQjfleVTV9Pps8wjMyw57SgxeHXmvadc9sbbD2AV bEA/bJhMuLOfEeZO+z94fv6dSdsIzmkj5ME63aZQn6fnYgfYaSwPPGfRKtHAWgce0vhb e1NUSsxihI5EeMzkBTyUEDq7dUBN0HVUyDULMt7t/9ksMrb2jf6iCrZCSxXFFfxT1BSu qCowRnaKKzq7TmZUbmTyBGTt2OPkOpRP2BOj5ATbsmLLAoNlltFsj2yjpOzHlBInptIS 7kCA== 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=ct264XXsXB4Yfv0geBlQAhYKTLlUfdyjxR0wyex+U9E=; b=XkZZ/CAymXeVdxIj5tCRwgcsylt91zNBYFRm6c1BMONSnhTWa+2/BY65yuvEKwEJPy dKTIiwL6ixis3lil17G8wx2zK9pVoFB7BGU3hlLY8t8PzeO3+/w3pdDcS70MOgGYgdOg jySBO74e16WMvXQMYdHNQeh4YsEpEO0hz7gXocxtfu8Ze5njtiq+LhVDDBRLwZ5KQwpN SN4LVNh/KbAxT4WNubhdsTTXE5KIxzJqes2ZkR81JM8oeAvN2FF7STuhcHHKBs9/ruxO oHHrQc1iV7osC2oJDAW8fPMBh1PeIGRocZySerFop2rX3AgbX/ke2NyMUul388MoenTv DlsA== X-Gm-Message-State: APjAAAXvgklPNFoGc3UAkK7iGhRec/caOKVIGsW7egoteacZMhLtnrbx G4uLfZKbSk8GyPh/YTFsnfp4R5v2lPuUfA== X-Google-Smtp-Source: APXvYqyy0BRSbES5IcsPtMWYPx2IOEkqlinv/Ia20uk5XvmQ2OyJmiSdsmBYVWOnlrtq/hcJiu0RSQ== X-Received: by 2002:adf:efc4:: with SMTP id i4mr16582406wrp.225.1582639496845; Tue, 25 Feb 2020 06:04:56 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:56 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 10/12] qga/qapi-schema.json: Add some headings Date: Tue, 25 Feb 2020 14:04:35 +0000 Message-Id: <20200225140437.20609-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::442 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. Signed-off-by: Peter Maydell --- qga/qapi-schema.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index f6fcb59f34b..d026f9478cf 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1,14 +1,18 @@ # *-*- Mode: 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 Tue Feb 25 14:04:36 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403939 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 2AFD413A4 for ; Tue, 25 Feb 2020 14:09:02 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id E656721744 for ; Tue, 25 Feb 2020 14:09:01 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="R1Y+mT6i" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E656721744 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57195 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6atR-00063T-0I for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:09:01 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44896) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6ape-0006zL-3m for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apY-0005L9-Qe for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:06 -0500 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:52849) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apY-0005Kl-GT for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:00 -0500 Received: by mail-wm1-x344.google.com with SMTP id p9so3130891wmc.2 for ; Tue, 25 Feb 2020 06:05:00 -0800 (PST) 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=rfB6aFnyMDHV8qgUZJ4NYi9OqE7EgeqrDtxkONHm7eg=; b=R1Y+mT6i3F9soc2z35ge1zpwd62tg6CtONy/C+oQn3kD+2wYAdEkTjc2lWzZ9yZtfy vcH0t8AzGFln0aCPMhifQ1BpcJtlErSBxiJnx7sghHI+DamXK9R5Ef+h8mOeSSh3a90U dnM2FIBaC3q3tSgOsdtLw8WfKtQTtPFW+w0epQTEXP3jGEN6ld8AqMpUBPxyaaJhaFpn Rn1xYMGOV4cVbdB5wDBgWftNQagceITPIoRc4U/yAOV7epyjxfGqk0uZDvFZ4dWX+VQM w+ixE3/wOBbRwdOTbrW/hXciowvtizqiqISAJtGcKhNjbkbc22HKS3Hyv77V4JpKB9JS uwoA== 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=rfB6aFnyMDHV8qgUZJ4NYi9OqE7EgeqrDtxkONHm7eg=; b=FwtWQWM90o4JuyBRPOTgmjGV26nF1PAeBRCC4/UVPxaEkScOhVfeZ8WNN2KlZRGPQs gOF5pa+mNkxPpMcVj9g5FFChjxaTGyIrpJXbet8Xw1o0pi4aww48Gf9F5iOUIpGYWqGK +X+qbzo/1vDfQ3Zb87mYweMVUDEoO+TUWdYNyPK+pIAV5+3usmJ2Yd9cXlonmF6gOoGp 0O5OGTKvajJpizXblrJe+rsxKcK6tVxGQG4UfDqWZrwX3DISSFh+8xpY0Q2XDazYlBOf GS4jBhQikXIkHVMbs273dTmW5qiAxC0N6ygsapJ540/RImhd+adQ52mywyocwcn72Vjz bzKA== X-Gm-Message-State: APjAAAUN6yB0jjxapCSRti7lW24kt4d5wMeWf8SslZBbDCu1arP0XdKg Qv16ZravHrRIQat9RLeIM+SwJqOQ6p06BA== X-Google-Smtp-Source: APXvYqyZe3AcuyxM45cBn0TdGnE54UI66LifqNIH3svq/Ktzb0lPjTadJWLN/9bvWc98rQVJtCbdLA== X-Received: by 2002:a05:600c:294a:: with SMTP id n10mr5629957wmd.11.1582639498531; Tue, 25 Feb 2020 06:04:58 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:57 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 11/12] scripts/qapi: Remove texinfo generation support Date: Tue, 25 Feb 2020 14:04:36 +0000 Message-Id: <20200225140437.20609-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::344 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. Signed-off-by: Peter Maydell --- Makefile | 1 - tests/Makefile.include | 15 +- scripts/qapi-gen.py | 2 - scripts/qapi/doc.py | 302 -------------------------------- scripts/qapi/gen.py | 7 - tests/qapi-schema/doc-good.texi | 281 ----------------------------- 6 files changed, 1 insertion(+), 607 deletions(-) delete mode 100644 scripts/qapi/doc.py delete mode 100644 tests/qapi-schema/doc-good.texi diff --git a/Makefile b/Makefile index f6e7f500416..191fd7f6e3f 100644 --- a/Makefile +++ b/Makefile @@ -611,7 +611,6 @@ qemu-keymap$(EXESUF): QEMU_CFLAGS += $(XKBCOMMON_CFLAGS) qapi-py = $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ diff --git a/tests/Makefile.include b/tests/Makefile.include index edcbd475aa7..ee84107e1be 100644 --- a/tests/Makefile.include +++ b/tests/Makefile.include @@ -32,7 +32,6 @@ export SRC_PATH qapi-py = $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ @@ -488,16 +487,8 @@ tests/test-qapi-gen-timestamp: \ $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ -o tests -p "test-" $<, \ "GEN","$(@:%-timestamp=%)") - @rm -f tests/test-qapi-doc.texi @>$@ -tests/qapi-schema/doc-good.test.texi: $(SRC_PATH)/tests/qapi-schema/doc-good.json $(qapi-py) - $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ - -o tests/qapi-schema -p "doc-good-" $<, \ - "GEN","$@") - @mv tests/qapi-schema/doc-good-qapi-doc.texi $@ - @rm -f tests/qapi-schema/doc-good-qapi-*.[ch] tests/qapi-schema/doc-good-qmp-*.[ch] - tests/qtest/dbus-vmstate1.h tests/qtest/dbus-vmstate1.c: tests/qtest/dbus-vmstate1-gen-timestamp ; tests/qtest/dbus-vmstate1-gen-timestamp: $(SRC_PATH)/tests/qtest/dbus-vmstate1.xml $(call quiet-command,$(GDBUS_CODEGEN) $< \ @@ -849,10 +840,6 @@ check-tests/qapi-schema/frontend: $(addprefix $(SRC_PATH)/, $(check-qapi-schema- PYTHONIOENCODING=utf-8 $(PYTHON) $(SRC_PATH)/tests/qapi-schema/test-qapi.py $^, \ TEST, check-qapi-schema) -.PHONY: check-tests/qapi-schema/doc-good.texi -check-tests/qapi-schema/doc-good.texi: tests/qapi-schema/doc-good.test.texi - @diff -u $(SRC_PATH)/tests/qapi-schema/doc-good.texi $< - .PHONY: check-decodetree check-decodetree: $(call quiet-command, \ @@ -900,7 +887,7 @@ check-acceptance: check-venv $(TESTS_RESULTS_DIR) # Consolidated targets .PHONY: check-block check-qapi-schema check-qtest check-unit check check-clean -check-qapi-schema: check-tests/qapi-schema/frontend check-tests/qapi-schema/doc-good.texi +check-qapi-schema: check-tests/qapi-schema/frontend check-qtest: $(patsubst %,check-qtest-%, $(QTEST_TARGETS)) ifeq ($(CONFIG_TOOLS),y) check-block: $(patsubst %,check-%, $(check-block-y)) diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py index 4b03f7d53be..541e8c1f55d 100755 --- 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 26cd1a1751e..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, 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, base, members, variants, - features): - 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, variants): - doc = self.cur_doc - self._gen.add(texi_type('Alternate', doc, ifcond, - texi_members(doc, 'Members'))) - - def visit_command(self, name, info, ifcond, arg_type, ret_type, gen, - success_response, boxed, allow_oob, allow_preconfig, - features): - 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, 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 95afae0615a..7712d2d49f7 100644 --- a/scripts/qapi/gen.py +++ b/scripts/qapi/gen.py @@ -177,13 +177,6 @@ def ifcontext(ifcond, *args): arg.end_if() -class QAPIGenDoc(QAPIGen): - - def _top(self): - return (QAPIGen._top(self) - + '@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 1e8063c8579..00000000000 --- a/tests/qapi-schema/doc-good.texi +++ /dev/null @@ -1,281 +0,0 @@ -@c AUTOMATICALLY GENERATED, DO NOT MODIFY - -@section Section - -@subsection Subsection - -@strong{strong} @emph{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 -@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 -@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 - -@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 - -@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 - -@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} - -@end deftypefn - From patchwork Tue Feb 25 14:04:37 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 11403951 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 7CB8014B4 for ; Tue, 25 Feb 2020 14:10:51 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 538E22072D for ; Tue, 25 Feb 2020 14:10:51 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=linaro.org header.i=@linaro.org header.b="JHu7Txlo" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 538E22072D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:57334 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6avC-0001iK-Hy for patchwork-qemu-devel@patchwork.kernel.org; Tue, 25 Feb 2020 09:10:50 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:44895) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6ape-0006zJ-3h for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:09 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6apa-0005Lv-6a for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:05 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:44754) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6apZ-0005LU-VT for qemu-devel@nongnu.org; Tue, 25 Feb 2020 09:05:02 -0500 Received: by mail-wr1-x444.google.com with SMTP id m16so14841249wrx.11 for ; Tue, 25 Feb 2020 06:05:01 -0800 (PST) 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=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=JHu7TxloT3KX2waltLkIpVoEDenjAD2ztHiqiak6sYff8A1NSuntmGoDyLY8VDNhxc 4UwNDAqo1k1E71E6CxWC0GRb7E3u/2Hfr+wD6em4VgkzgLrIjMrzCd5bA8ooBIZJ5qKt a5vSxUdIzaALLCn21nTjk7t1PeOXzgIC6vxlUs4GGCAqTQlFSI/Qi18l3V1Ch9Svo2sj iF+4pHYM57RHrdMK0SO3lhp5YhdQNyqVkKg5xeyq2LQYiaWidoeVZEVxf6qqfbTxz1Sa 2ogrfof/hBcs6IZ/McLwAAnMn1kLlkZ7TnhsmJsQK21DUEpYa5VOqQ5Ow3NIk5HqKrit dm6Q== 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=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=jnh4e30QNXxWWBO7ixlwGWux1yHvHuwfgFhWIjAXU9zYOsTjA370bTacGqzEyMDoI0 5V7KJGB4xLat4apMSGVL/XDTbzfLjMTZymbEAUhJHtgrJmOlfmxkP9mh9N0YglZi7D32 i4hXz43zQL4+ONDcq+7PJepNWanMhsLcTa9r6mjAOcUX+L2+qvo6ZzBhkc4msvh9M7wE l57ti+JxOwRUHng74Gttuk/jUpFnFFHoryKcZcjwbjjnbT2Ku/+Vxvt3w/7MWwPoefjf gzKIX9ySOx+41AhtwFYcfX7Dafo8E5NLdhFSF1qpVH5Z0lL+VUUqqEywEhSyCUbbuULm 3ZcQ== X-Gm-Message-State: APjAAAWxDtA0JLsIGxXDQZO7yQmi5/8Ph6EbEJJ2Sm5rEzPg4mT57dxf zascV1tCCg6P75kinUS4xa7V7BHHAXURFA== X-Google-Smtp-Source: APXvYqwxBz9CYilHgzPbcZX+odzzljyG5lGCLx6LOAj69R07mXb2aiMRDjw8ebExs1QK/mJeUaMHEA== X-Received: by 2002:a5d:6284:: with SMTP id k4mr75282963wru.398.1582639500247; Tue, 25 Feb 2020 06:05:00 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id f127sm4322136wma.4.2020.02.25.06.04.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 06:04:59 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v3 12/12] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Tue, 25 Feb 2020 14:04:37 +0000 Message-Id: <20200225140437.20609-13-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225140437.20609-1-peter.maydell@linaro.org> References: <20200225140437.20609-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 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: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.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. * headings and subheadings must now be in a freeform documentation comment of their own * we support arbitrary levels of sub- and sub-sub-heading, not just a main and sub-heading like the old texinfo generator Signed-off-by: Peter Maydell --- docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 59d6973e1ec..688eb2a0237 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -795,21 +795,39 @@ 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 single 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 + ## + +Section headings must always be correctly nested, so you can only +define a third-level heading inside a second-level heading, and so +on. The documentation generator will catch nesting mistakes and report +a syntax error. ==== 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 - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines '*' starts an itemized list: @@ -825,37 +843,35 @@ 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 **bol** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## - ==== Definition documentation ==== Definition documentation, if present, must immediately precede the @@ -870,6 +886,12 @@ 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; if they +do then the second and subsequent lines must be indented +to line up with the first character of the first line of the +description. The parser will report a syntax error if there +is insufficient indentation. + FIXME: the parser accepts these things in almost any order. FIXME: union branches should be described, too. @@ -883,6 +905,16 @@ The section ends with the start of a new section. 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: ##