@@ -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 ``<DOCNAME-HXFILE-LABEL>``, 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,
+``<system/invocation-qemu-options-initrd>``.
``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.
@@ -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,14 @@ def run(self):
serror(hxfile, lnum, 'expected ERST, found SRST')
else:
state = HxState.RST
+ label = parse_srst(hxfile, lnum, line)
+ if label:
+ rstlist.append("", hxfile, lnum - 1)
+ # Build label as _DOCNAME-HXNAME-LABEL
+ hx = os.path.splitext(os.path.basename(hxfile))[0]
+ refline = ".. _" + env.docname + "-" + hx + \
+ "-" + label + ":"
+ rstlist.append(refline, hxfile, lnum - 1)
elif directive == 'ERST':
if state == HxState.CTEXT:
serror(hxfile, lnum, 'expected SRST, found ERST')
@@ -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 <system/invocation-qemu-options-initrd>` for the
+``-initrd`` option.
Host OS requirements
--------------------
@@ -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.