From nobody Thu Nov 13 20:40:36 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1582639868; cv=none; d=zohomail.com; s=zohoarc; b=HhjtyhEktn5giCAgDGyGjNsMhPSFMoa7u/eio3FSxLuNnoUjZ4Oj/TMaDHWrTk8yaxn1YlHyIY0wNLv040BgNdzqhvGM/7XsBPjLI8Yjd9ZOs993E4CW7EY6XfyQWutZPxA1FJZuRo9JBWiDVswFUSYMx2A5FVGLRGqnolsxTvI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1582639868; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=dDIrVYYfe8HyQltAbZSYI/kQst07Km5oAiPk7rwRe7Pp1RddGJIe9Cg1D403ka2P+QNZYqQhhjDAlt5tFk+JELoUet//AjtjkdeoeRNKJROZa1HVX1Um8SgScIitbgDOTOe/IeOtsqQNMkD3bCfHyoa60TFP+JyLblKO1n5MQzY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1582639868576963.6049751013045; Tue, 25 Feb 2020 06:11:08 -0800 (PST) Received: from localhost ([::1]:57334 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6avT-0001iK-Nk for importer@patchew.org; Tue, 25 Feb 2020 09:11:07 -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) 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) 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) 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 Content-Transfer-Encoding: quoted-printable 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=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" 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. =20 +=3D=3D=3D=3D Headings and subheadings =3D=3D=3D=3D + +A free-form documentation comment containing a single line +which starts with some '=3D' symbols and then a space defines +a section heading: + + ## + # =3D This is a top level heading + ## + + ## + # This is a free-form comment which will go under the + # top level heading. + ## + + ## + # =3D=3D 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. =20 =3D=3D=3D=3D Documentation markup =3D=3D=3D=3D =20 -Comment text starting with '=3D' is a section title: +Documentation comments can use most rST markup. In particular, +a '::' literal block can be used for examples: =20 - # =3D Section title - -Double the '=3D' for a subsection title: - - # =3D=3D Subsection title - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines =20 '*' starts an itemized list: =20 @@ -825,37 +843,35 @@ A decimal number followed by '.' starts a numbered li= st: # multiple lines # 2. Second item =20 -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. +The actual number doesn't matter. =20 -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. =20 -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-escap= e 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``'. =20 Example: =20 ## -# =3D Section -# =3D=3D 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 ## =20 - =3D=3D=3D=3D Definition documentation =3D=3D=3D=3D =20 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. =20 +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. =20 @@ -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. =20 +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: =20 ## --=20 2.20.1