| Message ID | 20240130190348.682912-1-dwmw2@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v4] doc/sphinx/hxtool.py: add optional label argument to SRST directive | expand |
On Tue, 30 Jan 2024 at 19:04, David Woodhouse <dwmw2@infradead.org> wrote: > > 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 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> > --- > v4: > • Wrap long lines to shut checkpatch up Applied to target-arm.next, thanks. PS: for checkpatch long lines, note that our coding style doc permits line lengths which checkpatch will warn about, if it would be "obviously less readable" than wrapping. So that particular warning is more of a "look at this and see if it could be written in a different way" rather than a "definitely change this to get rid of the warning" one. (At some point I might try to go back and get the discrepancy between what our coding style doc says checkpatch complains about and what it actually complains about straightened out. The underlying issue is that there's no consensus between whether it's better that: * checkpatch produces a warning on code that's in a "grey area" where we might be OK with it but it might be better to change it, so that the patch submitter is prompted to look at that part of the change and consider altering it * checkpatch doesn't warn about "grey area" situations, so that we don't have "checkpatch complains but we're actually happy with the patch and wouldn't want it changed" situations ) -- PMM
diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst index 7da067905b..50ff0d67f8 100644 --- a/docs/devel/docs.rst +++ b/docs/devel/docs.rst @@ -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. diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py index 9f6b9d87dc..3729084a36 100644 --- a/docs/sphinx/hxtool.py +++ b/docs/sphinx/hxtool.py @@ -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') diff --git a/docs/system/i386/xen.rst b/docs/system/i386/xen.rst index 81898768ba..46db5f34c1 100644 --- a/docs/system/i386/xen.rst +++ b/docs/system/i386/xen.rst @@ -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 -------------------- 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.