From c26fb2a725bc3a5ba3af0f3273b2ab06f58f1135 Mon Sep 17 00:00:00 2001 From: David Woodhouse Date: Mon, 6 Nov 2023 13:34:05 +0000 Subject: [PATCH] doc/sphinx/hxtool.py: add optional label argument to SRST directive 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 'emitrefs' option to the Sphinx hxtool-doc directive, which is set only in invocation.rst and not from the HTML rendition of the man page. Along with an argument to the SRST directive which causes a label of the form '.. _LABEL-reference-label:' to be emitted when the emitrefs option is set. Now where the Xen PV documentation refers to the documentation for the -initrd command line option, it can emit a link directly to it. Signed-off-by: David Woodhouse Reviewed-by: Paul Durrant --- docs/sphinx/hxtool.py | 18 +++++++++++++++++- docs/system/i386/xen.rst | 2 +- docs/system/invocation.rst | 1 + qemu-options.hx | 2 +- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py index 9f6b9d87dc..bfb0929573 100644 --- a/docs/sphinx/hxtool.py +++ b/docs/sphinx/hxtool.py @@ -78,18 +78,28 @@ 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 "SRST(label)". + match = re.match(r'SRST\((.*?)\)', line) + if match is None: + serror(file, lnum, "Invalid SRST line") + return match.group(1) + class HxtoolDocDirective(Directive): """Extract rST fragments from the specified .hx file""" required_argument = 1 optional_arguments = 1 option_spec = { - 'hxfile': directives.unchanged_required + 'hxfile': directives.unchanged_required, + 'emitrefs': directives.flag } has_content = False def run(self): env = self.state.document.settings.env hxfile = env.config.hxtool_srctree + '/' + self.arguments[0] + emitrefs = "emitrefs" in self.options # Tell sphinx of the dependency env.note_dependency(os.path.abspath(hxfile)) @@ -113,6 +123,12 @@ class HxtoolDocDirective(Directive): serror(hxfile, lnum, 'expected ERST, found SRST') else: state = HxState.RST + if emitrefs and line != "SRST": + label = parse_srst(hxfile, lnum, line) + if label != "": + rstlist.append("", hxfile, lnum - 1) + refline = ".. _" + label + "-reference-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..536dd6a2f9 100644 --- a/docs/system/i386/xen.rst +++ b/docs/system/i386/xen.rst @@ -132,7 +132,7 @@ 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/docs/system/invocation.rst b/docs/system/invocation.rst index 14b7db1c10..06a99dadc0 100644 --- a/docs/system/invocation.rst +++ b/docs/system/invocation.rst @@ -16,6 +16,7 @@ double the commas. For instance,"-fw_cfg name=z,string=a,,b" will be parsed as "-fw_cfg name=z,string=a,b". .. hxtool-doc:: qemu-options.hx + :emitrefs: Device URL Syntax ~~~~~~~~~~~~~~~~~ diff --git a/qemu-options.hx b/qemu-options.hx index b66570ae00..e4ffdf8118 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -4002,7 +4002,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. -- 2.50.1