| Message ID | 4114f7204e892316d66be8f810eb5b8de4c0f75f.camel@infradead.org |
|---|---|
| State | New |
| Headers | show |
| Series | [v3] doc/sphinx/hxtool.py: add optional label argument to SRST directive | expand |
On Sat, 27 Jan 2024 at 23:18, 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> > --- This looks good so Reviewed-by: Peter Maydell <peter.maydell@linaro.org> but something has got mangled somewhere: patchew can't apply it: https://patchew.org/QEMU/4114f7204e892316d66be8f810eb5b8de4c0f75f.camel@infradead.org/ and patches doesn't like it either. In both cases git am barfs with error: corrupt patch at line 23 I'm guessing it doesn't like the quoted-printable encoding. thanks -- PMM
On Tue, 2024-01-30 at 17:55 +0000, Peter Maydell wrote: > > This looks good so > Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Thanks. > but something has got mangled somewhere: patchew can't apply it: > https://patchew.org/QEMU/4114f7204e892316d66be8f810eb5b8de4c0f75f.camel@infradead.org/ > and patches doesn't like it either. In both cases git am barfs with > > error: corrupt patch at line 23 > > I'm guessing it doesn't like the quoted-printable encoding. Nah, QP really ought to be fine. The problem is that for some reason Evolution has decided to replace space characters with non-breaking- space characters. That is a new and strange pathology... in a version of Evolution that I haven't updated for over a year. I'll send a v4 with git-send-email, as checkpatch was whinging about line lengths anyway.
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..e997d47d85 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,12 @@ def run(self): serror(hxfile, lnum, 'expected ERST, found SRST') else: state = HxState.RST + label = parse_srst(hxfile, lnum, line) + if label: + basename = os.path.splitext(os.path.basename(hxfile))[0] + rstlist.append("", hxfile, lnum - 1) + refline = ".. _" + env.docname + "-" + 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 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.