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 <dwmw@amazon.co.uk>
Reviewed-by: Paul Durrant <paul@xen.org>

diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py
index 9f6b9d87dccf5cd81361f8cd4d9bb1447bea45ef..bfb0929573d6865aeb63a58fc90a9a9a3f07609c 100644 (file)
--- 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 81898768baaaaf10fbc2a7390fd7a8aad0ad6cdf..536dd6a2f932faa7460cc0900aab0da65cc95d8c 100644 (file)
--- 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 <initrd-reference-label>` for the ``-initrd`` option.
 
 Host OS requirements
 --------------------

diff --git a/docs/system/invocation.rst b/docs/system/invocation.rst
index 14b7db1c102bc859b03af0903cac503d72f9f6de..06a99dadc0fec373b495e18e9e6193d8e090ac53 100644 (file)
--- 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 b66570ae006768cfe1263943c018c71df97dfe77..e4ffdf8118817acebbacbfaef62a59884d6821ca 100644 (file)
--- 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.