From: David Woodhouse <dwmw@amazon.co.uk>

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 '.. _BASENAME-LABEL:' to be emitted when the emitrefs option
is set, where BASENAME is the name of the .hx file and LABEL is the text
provided within the parentheses of the SRST() directive.

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 <dwmw@amazon.co.uk>
Reviewed-by: Paul Durrant <paul@xen.org>
---
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        |  4 ++++
 docs/sphinx/hxtool.py      | 18 +++++++++++++++++-
 docs/system/i386/xen.rst   |  2 +-
 docs/system/invocation.rst |  1 +
 qemu-options.hx            |  2 +-
 5 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst
index 7da067905b..17a199a0d4 100644
--- a/docs/devel/docs.rst
+++ b/docs/devel/docs.rst
@@ -30,6 +30,10 @@ 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, when used from
+a ``.hx`` file with the ``emitrefs`` option set in its Sphinx hxtool-doc
+directive.
 
 ``ERST`` ends the documentation section started with ``SRST``,
 and switches back to a C code section.
diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py
index 9f6b9d87dc..ec1ec56600 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 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
     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 @@ def run(self):
                         serror(hxfile, lnum, 'expected ERST, found SRST')
                     else:
                         state = HxState.RST
+                        label = parse_srst(hxfile, lnum, line)
+                        if emitrefs and label:
+                            basename = os.path.splitext(os.path.basename(hxfile))[0]
+                            rstlist.append("", hxfile, lnum - 1)
+                            refline = ".. _" + 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..8b7e35434f 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 <qemu-options-initrd>` 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 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.
-- 
2.43.0