From patchwork Fri Feb 2 15:36:13 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 769202 Delivered-To: patch@linaro.org Received: by 2002:adf:9bca:0:b0:33a:e5bd:fedd with SMTP id e10csp972861wrc; Fri, 2 Feb 2024 07:37:08 -0800 (PST) X-Google-Smtp-Source: AGHT+IEpiGObIJZQgczixz0+wRPJNvNfEV4c+Wj0sWpeoAoNa03LQQEKOcb56alP2itAxvySvaew X-Received: by 2002:a05:6358:1901:b0:178:a295:996 with SMTP id w1-20020a056358190100b00178a2950996mr9424410rwm.22.1706888228114; Fri, 02 Feb 2024 07:37:08 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1706888228; cv=none; d=google.com; s=arc-20160816; b=Ik9qsEEqGMXD/5husZDzM6JhrXNfngkn5baE+h2b+pUCRE7ChT93AVqHPDHpJSjr1r XwcuwyKJ+8sUfR1cg3YLpq3AUX/5NdfdzVVwR7vMkrJIV2odfooV1lVZd6y/JdqOlPjv LcG5zJntOYadL7uSBFq8RyfZ1WKW9aCg1cXu3IrY53oJ8AHOsoOFCV5TRYCggAXwo2pf /X+MAKByNObSjyir5q0+4iiN+UQxaIazZrTjLFMwyksQSVFHyvJWlmgxxhjXHDuvcCGf Qd2vn3QhlrFzAcB3gBgOZJN4/8J9IgyOLFu99anRTpYZIrPT6Gdm4z7FWULuk1a9fmL4 sBxQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to: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=nCqjBY1O075hml0hoLAI8QgIMrH8pjs6AsQwwZz+6WI=; fh=QxByAEu6zMrP/NXVMCQ51ftr9mZFJo6Kx9OcvrjifJ0=; b=AbDKJSHZiXar+PAkfLwAVq2ax9BKz6YZ6ShI7qXYaXsMXLo4FA0jFCjj2W2Ko8w9p9 0JEqd0twyh1F7pKe9CJcOchUfynvvvKW/QHH3rIU1QtY00iClDnVD1h4OeWxtwNSld67 00vaKaTEdCRCmU26wFstbKginR2lz+5IYOCok6nOOwbx5TSxyaE1JRconjhEZDcJOrMU BvVwMCs6WNXs6BGM/P3g1jLWJnI3tQe/4ALEqYq2YigI5CPlPHeC4ZlUjPuZVx4Uc3jn zy+li8MZCiry9DCEIrHenvMhXEreVDoeBOhKUHOG72qB3CaKhLxqiizXn0AFpsPN765y DgWw==; darn=linaro.org ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=nCLyTWnI; 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 X-Forwarded-Encrypted: i=0; AJvYcCUs0s0yZR+gdWQmqKmDTNQvfIXz3j7C9lCKatl/tX/YK6AUoaP+FiwIviBV8aIjwzJ1W9zsSFoa/ssh2AOdKRFd Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id q2-20020a056214194200b0068c8c1d5a1csi338708qvk.314.2024.02.02.07.37.07 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Fri, 02 Feb 2024 07:37:08 -0800 (PST) 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=nCLyTWnI; 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] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rVvb2-0000Kr-R5; Fri, 02 Feb 2024 10:36:52 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rVvb1-0000Jy-0O for qemu-devel@nongnu.org; Fri, 02 Feb 2024 10:36:51 -0500 Received: from mail-wm1-x332.google.com ([2a00:1450:4864:20::332]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rVvav-0004Sh-Rl for qemu-devel@nongnu.org; Fri, 02 Feb 2024 10:36:50 -0500 Received: by mail-wm1-x332.google.com with SMTP id 5b1f17b1804b1-40fafae5532so19305655e9.1 for ; Fri, 02 Feb 2024 07:36:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1706888204; x=1707493004; darn=nongnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=nCqjBY1O075hml0hoLAI8QgIMrH8pjs6AsQwwZz+6WI=; b=nCLyTWnIsyjV0cheIj1FvsDJsf+3TB27/J8OmfO40uLPSpmzTc6/1cWlqkagG1auA1 xdMaDotmy+6lF2w5YVw//DRD7oYpN0Y9xz3fm829aYf0SYOpspKcPEjjoY8bXoekXOoD xHL8l8ghBLOytZdCW4Yag+FQy4aLVO22yrRpQ5Tn9coRTtNVc2Dza8VrGIK/UR8cSxgj AL4T0e0aJhZhQ7xtAhD+TS/Lv9BIADssWdYlChN08ruYRZFPKxevXgWOTmgJGoWcCznh BYF6AvJWJ0Xp6LUpjlNcfB0FMrmsxK+9DnIS9ICmA1IFcew6+j8llzYQREbDxxh7/mfh 5wsA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1706888204; x=1707493004; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=nCqjBY1O075hml0hoLAI8QgIMrH8pjs6AsQwwZz+6WI=; b=EOdOZiVh8/yXNfsbYsvuXU3TbxnqUNdUpnBNHVzCq4749wooZ2Tcp1hxSo+w2hnMGb tX+e5oRPneuEotG96IYgsVgfdpxyerCnwCjz6p6TGiJq0yY+sXvR+zJAQgKwICEqKsFY ftnK2AmjIZZptEreRTFCzQ4u65kjKRgd0c5DKX8UU1UPWTY7n47Esp+xjhbVY/JMeu2x +B6+cXOIZT1RewTz1O+/I7yLqml4XBisWtM3j0jPGOKyx5vJbSjpZeR4MplumVKmo9OO h/GmBzbS4ClAPl0Z6KiMSg67i+Qf5kI/tyewpSLDcybH/+SeGTZp5qPbqyDjt/HMNir/ Mgpg== X-Gm-Message-State: AOJu0YxtRtpprdTJxjyYdrsCAqvbjkfheH3IlFNnGorgelbW2Ku63e4L GXps5DiO+liookl/D2tKAouyKpkA6oPauAATC0vXgYPpXCwja76XasZINauAajHXNIpLH6EVgKi 6 X-Received: by 2002:a5d:4c90:0:b0:33b:1bed:a315 with SMTP id z16-20020a5d4c90000000b0033b1beda315mr2414170wrs.25.1706888204443; Fri, 02 Feb 2024 07:36:44 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id k2-20020a05600c1c8200b0040fafd84095sm214735wms.41.2024.02.02.07.36.44 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 02 Feb 2024 07:36:44 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 12/36] doc/sphinx/hxtool.py: add optional label argument to SRST directive Date: Fri, 2 Feb 2024 15:36:13 +0000 Message-Id: <20240202153637.3710444-13-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240202153637.3710444-1-peter.maydell@linaro.org> References: <20240202153637.3710444-1-peter.maydell@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::332; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x332.google.com 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_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_HELO_TEMPERROR=0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org From: David Woodhouse We can't just embed labels directly into files like qemu-options.hx which are included from multiple top-level rST files, because Sphinx sees the labels as duplicate: https://github.com/sphinx-doc/sphinx/issues/9707 So add an optional argument to the SRST directive which causes a label of the form '.. _DOCNAME-HXFILE-LABEL:' to be emitted, where 'DOCNAME' is the name of the top level rST file, 'HXFILE' is the filename of the .hx file, and 'LABEL' is the text provided within the 'SRST()' directive. Using the DOCNAME of the top-level rST document means that it is unique even when the .hx file is included from two different documents, as is the case for qemu-options.hx Now where the Xen PV documentation refers to the documentation for the -initrd command line option, it can emit a link directly to it as ''. Signed-off-by: David Woodhouse Reviewed-by: Paul Durrant Reviewed-by: Peter Maydell Message-id: 20240130190348.682912-1-dwmw2@infradead.org Signed-off-by: Peter Maydell --- docs/devel/docs.rst | 12 ++++++++++-- docs/sphinx/hxtool.py | 16 ++++++++++++++++ docs/system/i386/xen.rst | 3 ++- qemu-options.hx | 2 +- 4 files changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst index 7da067905b8..50ff0d67f84 100644 --- a/docs/devel/docs.rst +++ b/docs/devel/docs.rst @@ -30,6 +30,13 @@ nor the documentation output. ``SRST`` starts a reStructuredText section. Following lines are put into the documentation verbatim, and discarded from the C output. +The alternative form ``SRST()`` is used to define a label which can be +referenced from elsewhere in the rST documentation. The label will take +the form ````, where ``DOCNAME`` is the name of the +top level rST file, ``HXFILE`` is the filename of the .hx file without +the ``.hx`` extension, and ``LABEL`` is the text provided within the +``SRST()`` directive. For example, +````. ``ERST`` ends the documentation section started with ``SRST``, and switches back to a C code section. @@ -53,8 +60,9 @@ text, but in ``hmp-commands.hx`` the C code sections are elements of an array of structs of type ``HMPCommand`` which define the name, behaviour and help text for each monitor command. -In the file ``qemu-options.hx``, do not try to define a +In the file ``qemu-options.hx``, do not try to explicitly define a reStructuredText label within a documentation section. This file is included into two separate Sphinx documents, and some versions of Sphinx will complain about the duplicate label -that results. +that results. Use the ``SRST()`` directive documented above, to +emit an unambiguous label. diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py index 9f6b9d87dcc..3729084a36c 100644 --- a/docs/sphinx/hxtool.py +++ b/docs/sphinx/hxtool.py @@ -78,6 +78,14 @@ def parse_archheading(file, lnum, line): serror(file, lnum, "Invalid ARCHHEADING line") return match.group(1) +def parse_srst(file, lnum, line): + """Handle an SRST directive""" + # The input should be either "SRST", or "SRST(label)". + match = re.match(r'SRST(\((.*?)\))?', line) + if match is None: + serror(file, lnum, "Invalid SRST line") + return match.group(2) + class HxtoolDocDirective(Directive): """Extract rST fragments from the specified .hx file""" required_argument = 1 @@ -113,6 +121,14 @@ def run(self): serror(hxfile, lnum, 'expected ERST, found SRST') else: state = HxState.RST + label = parse_srst(hxfile, lnum, line) + if label: + rstlist.append("", hxfile, lnum - 1) + # Build label as _DOCNAME-HXNAME-LABEL + hx = os.path.splitext(os.path.basename(hxfile))[0] + refline = ".. _" + env.docname + "-" + hx + \ + "-" + label + ":" + rstlist.append(refline, hxfile, lnum - 1) elif directive == 'ERST': if state == HxState.CTEXT: serror(hxfile, lnum, 'expected SRST, found ERST') diff --git a/docs/system/i386/xen.rst b/docs/system/i386/xen.rst index 81898768baa..46db5f34c1d 100644 --- a/docs/system/i386/xen.rst +++ b/docs/system/i386/xen.rst @@ -132,7 +132,8 @@ The example above provides the guest kernel command line after a separator (" ``--`` ") on the Xen command line, and does not provide the guest kernel with an actual initramfs, which would need to listed as a second multiboot module. For more complicated alternatives, see the command line -documentation for the ``-initrd`` option. +:ref:`documentation ` for the +``-initrd`` option. Host OS requirements -------------------- diff --git a/qemu-options.hx b/qemu-options.hx index 40e938c4877..5adbed11013 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -3994,7 +3994,7 @@ ERST DEF("initrd", HAS_ARG, QEMU_OPTION_initrd, \ "-initrd file use 'file' as initial ram disk\n", QEMU_ARCH_ALL) -SRST +SRST(initrd) ``-initrd file`` Use file as initial ram disk.