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 '.. _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>

diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst
index 7da067905b846f2fbdbb0f1086c4ab98088f13ed..17a199a0d4bd2b3deeab95743f5b4ec3cfd77d90 100644 (file)
--- 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 9f6b9d87dccf5cd81361f8cd4d9bb1447bea45ef..ec1ec56600a7ba3bcf9a9abdff358f2c486f33d2 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 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 @@ class HxtoolDocDirective(Directive):
                         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 81898768baaaaf10fbc2a7390fd7a8aad0ad6cdf..8b7e35434fed0807bac8af151ba959bc8b78f202 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 <qemu-options-initrd>` 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 ced82848637623defe430614182b1e0b70a780ff..b3ff06b0b68485c2b11f6396f8fa624a0fa15376 100644 (file)
--- 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.