1
0
mirror of https://gitlab.com/qemu-project/qemu synced 2024-07-08 20:17:27 +00:00

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 optional argument to the SRST directive which causes a label
of the form '.. _DOCNAME-HXFILE-LABEL:' to be emitted, where 'DOCNAME'
is the name of the top level rST file, 'HXFILE' is the filename of the
.hx file, and 'LABEL' is the text provided within the 'SRST()' directive.
Using the DOCNAME of the top-level rST document means that it is unique
even when the .hx file is included from two different documents, as is
the case for qemu-options.hx

Now where the Xen PV documentation refers to the documentation for the
-initrd command line option, it can emit a link directly to it as
'<system/invocation-qemu-options-initrd>'.

Signed-off-by: David Woodhouse <dwmw@amazon.co.uk>
Reviewed-by: Paul Durrant <paul@xen.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20240130190348.682912-1-dwmw2@infradead.org
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
David Woodhouse 2024-01-30 19:01:43 +00:00 committed by Peter Maydell
parent 185e3fdf8d
commit 1eeb432a95
4 changed files with 29 additions and 4 deletions

View File

@ -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.

View File

@ -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')

View File

@ -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
--------------------

View File

@ -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.