From patchwork Sat Jan 27 23:18:16 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: David Woodhouse X-Patchwork-Id: 13534255 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org 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 smtp.lore.kernel.org (Postfix) with ESMTPS id 65F33C46CD2 for ; Sat, 27 Jan 2024 23:19:20 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rTrwQ-0001tt-SB; Sat, 27 Jan 2024 18:18:27 -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 1rTrwO-0001tV-Oq for qemu-devel@nongnu.org; Sat, 27 Jan 2024 18:18:25 -0500 Received: from casper.infradead.org ([2001:8b0:10b:1236::1]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rTrwM-0002GN-5n for qemu-devel@nongnu.org; Sat, 27 Jan 2024 18:18:24 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=MIME-Version:Content-Type:Date:Cc:To: From:Subject:Message-ID:Sender:Reply-To:Content-Transfer-Encoding:Content-ID: Content-Description:In-Reply-To:References; bh=66Zwuu3jkX+1LZIuWdm5MTjKvwnCDPd55gl/IOV70d4=; b=cCL8Axs21ENWJ6b86egBeq9V3o 8okipnGI5YKv4Tojkhp7AXN6cx0odu3m8NLsIUQkiU9ddM1OBPuQgRcMMhvu9tKZvjvk8yyBl2fhW ZhuOtY1km4fLxDOA1JnrxlQwF9jhnyaoBHNnZ0xkSQxvLuhVudX7eNSpJBfx73UL3j1JuyyFwJFGV qV2KrFwcbJD5RfGj87XvV6DGE3xEGQWhU7/xGahhTAlZkz4UwCBCefHTm0uFiVfOK6eS+7DqjMBhd w8i6UCYzfaN+F9ifi5ZhwAUAYlSWAR2kzGJitJ9ZNNDzwWpfAa3K+uAkU1ijOjSAzWAisJJYaYQFG EQV5Pvkg==; Received: from [2001:8b0:10b:5:3d17:8278:e887:438f] (helo=u3832b3a9db3152.ant.amazon.com) by casper.infradead.org with esmtpsa (Exim 4.97.1 #2 (Red Hat Linux)) id 1rTrwF-00000000f8c-2uxf; Sat, 27 Jan 2024 23:18:17 +0000 Message-ID: <4114f7204e892316d66be8f810eb5b8de4c0f75f.camel@infradead.org> Subject: [PATCH v3] doc/sphinx/hxtool.py: add optional label argument to SRST directive From: David Woodhouse To: Peter Maydell Cc: "qemu-devel@nongnu.org" Date: Sat, 27 Jan 2024 23:18:16 +0000 User-Agent: Evolution 3.44.4-0ubuntu2 MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by casper.infradead.org. See http://www.infradead.org/rpr.html Received-SPF: none client-ip=2001:8b0:10b:1236::1; envelope-from=BATV+2d71f3dbc0876e822724+7461+infradead.org+dwmw2@casper.srs.infradead.org; helo=casper.infradead.org X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 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_MED=-2.3, SPF_HELO_NONE=0.001, SPF_NONE=0.001, T_SCC_BODY_TEXT_LINE=-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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.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 --- v3: • Include DOCNAME in label • Drop emitrefs option which is no longer needed v2: • Invoke parse_srst() unconditionally • Change emitted label to include basename of .hx file • Describe it in docs/devel/docs.rst  docs/devel/docs.rst      | 12 ++++++++++--  docs/sphinx/hxtool.py    | 14 ++++++++++++++  docs/system/i386/xen.rst |  3 ++-  qemu-options.hx          |  2 +-  4 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst index 7da067905b..50ff0d67f8 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 9f6b9d87dc..e997d47d85 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,12 @@ def run(self):                          serror(hxfile, lnum, 'expected ERST, found SRST')                      else:                          state = HxState.RST +                        label = parse_srst(hxfile, lnum, line) +                        if label: +                            basename = os.path.splitext(os.path.basename(hxfile))[0] +                            rstlist.append("", hxfile, lnum - 1) +                            refline = ".. _" + env.docname + "-" + basename + "-" + 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 81898768ba..46db5f34c1 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 ced8284863..b3ff06b0b6 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.