From patchwork Mon Aug 10 19:50:14 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 247600 Delivered-To: patch@linaro.org Received: by 2002:a92:cc90:0:0:0:0:0 with SMTP id x16csp5170740ilo; Mon, 10 Aug 2020 12:55:27 -0700 (PDT) X-Google-Smtp-Source: ABdhPJysKX08KHTeekNeB75uPRiFyctauTmCds/BGf+s7orGHdpnP76A2M9L5XOLl6rO1mVZng4M X-Received: by 2002:a25:84cd:: with SMTP id x13mr42860996ybm.425.1597089327054; Mon, 10 Aug 2020 12:55:27 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1597089327; cv=none; d=google.com; s=arc-20160816; b=Iqu7iBj547YFDK8TUW8sSdUYyZqR6kxYuRoxYitZIhv48vwcIsEw5hql0JO4T0/NNR GKpaoE8e+cSM/NmKdlWQa3mRQM7OT/rXNtTElTY1h3vDXYJB4pek3bksrHxNJLyOTg5g Og1cM/9lX55uEdSiD5rs4YVzrbPmO7lpNly2ftMTZbH4ZUQ84ffeSp2uDtn22GJ2jVXO J00U4CwFWm4TSI5s8JORBJOWK2JW63UOncrAq+xXVYlL3ULGK8eO/D63BxSKlJrryU9p y8zGkGqhy0mN5t1i9E2mSI3SNT/CVNHLu9rdEKYcDpjd0jR6b3J/TDEail4qwRJfsU+z G6Wg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=cp52Tz1lECqYI3uEVQbbG4Lu/4PnK1R1by9RglA8G/g=; b=KIKdfOGLg0ELzG8uSmFVHT1Cv0F3YRxkgPUo4z1Qh3KrXbdha97LzOzR6D0hpJqqt9 Y3QLWNgWOGfev8XajqE7LYS0+dvdLZkXfVtAcFTx7Lh4e4SqARfKUjo8ffSo31GDW4KM hWUNHndlJ158RkrEj3+tft6im+7X9718q0YiAbLn0sJlgvaU8rv2bXBl96ZXvV6fsKgn N9RYUBnxyofn3iU8Kj4NJqovvLav6Z7qtmd+3/WwAdgEJ2EnXR/69fBSRvTSbMftzoml vg0j+vSRDE/MeQ5DLYfmhqmOS6XgDbXCEu6F9oJrV1uAuYh+t3vefuJafdQS76r5DaCB qKTQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=zLSxyn2l; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id g93si17423675ybi.26.2020.08.10.12.55.26 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Mon, 10 Aug 2020 12:55:27 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=zLSxyn2l; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:54144 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5DtG-0001o2-3G for patch@linaro.org; Mon, 10 Aug 2020 15:55:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51240) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5Doq-0000sO-8V for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:52 -0400 Received: from mail-wm1-x32c.google.com ([2a00:1450:4864:20::32c]:52422) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1k5Don-0004tG-VB for qemu-devel@nongnu.org; Mon, 10 Aug 2020 15:50:51 -0400 Received: by mail-wm1-x32c.google.com with SMTP id x5so606191wmi.2 for ; Mon, 10 Aug 2020 12:50:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cp52Tz1lECqYI3uEVQbbG4Lu/4PnK1R1by9RglA8G/g=; b=zLSxyn2lgqXet73mPvGJK+Yi84f3FsWZcQSRGfjvGHe8BNBMvyp/cOf96+pIyUk2sB DIXItBkcyIFGZ50H24jTGL+P8uumiNnIvXYlz1/0xbIQpCnsEXIaXcZRRfjq8ri1u0v9 0OSra/3UyNq1gmJm6XrtoFcIbv8Grzjf9u3d7u9NolIY3mk/EsyxG5p1yLDeUu21jUw9 wlOhok6emZubW5p5Q7WfHji9YY0+w/4ZmOafuzfrc9byfwc672k5jIUv0z1m1H58Yp+4 s4b6b9uglprNjJJ2yul4a8phM130aksvHn9rsP3pOurLn+gL48haNU6jUUGPtlsjl9oA 1F3w== 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=cp52Tz1lECqYI3uEVQbbG4Lu/4PnK1R1by9RglA8G/g=; b=UdWp4VG81sn44rVX3q0P9GG6seOGrqeClYOG6tTnvJyz+9woareFkWsi1dc0sSIbMS WGqIyNN7BGdz4Iz3o68DCrfrneS99zKdvovy55pqbpY+ftEw0059MM4sXyIv2YBkmHKR 0PQY2cNY9CCnHizJWDXsO1pJzJFnZfYDLyH4bGMDEw1NgYbiSoL8W36S9ipxMFlfH3Xn xrmlkZ5CC0iCuT2V45hiP2xeQdYHqkSNYUgkk7HPpmGbNI/Y1UDg/MlxOyt/AsRB9FHG IA1L88QzK4PEqnABuPCbV7cJQYhIDdkXXh7qeibtjd8WbZKDJoLxGfLlOXp4pc9D1wIt MvRA== X-Gm-Message-State: AOAM532NzMiiVDCyM49ltODO5NVWoWPFIsgUSBHs8FQ7GtsGP0xiZeuw 8JdD984k4JXPvspbLUp9OLGgdIMXjjs+1g== X-Received: by 2002:a05:600c:2888:: with SMTP id g8mr802278wmd.118.1597089047684; Mon, 10 Aug 2020 12:50:47 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b129sm976087wmb.29.2020.08.10.12.50.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Aug 2020 12:50:46 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Mon, 10 Aug 2020 20:50:14 +0100 Message-Id: <20200810195019.25427-16-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200810195019.25427-1-peter.maydell@linaro.org> References: <20200810195019.25427-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32c; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32c.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Markus Armbruster Errors-To: qemu-devel-bounces+patch=linaro.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 Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell --- docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 29 deletions(-) -- 2.20.1 diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 69eede6c283..263f1c0b44c 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -824,21 +824,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: @@ -854,37 +872,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 @@ -899,6 +915,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. @@ -912,6 +934,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: ##