| Message ID | 20231106143507.1060610-17-dwmw2@infradead.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Get Xen PV shim running in QEMU, add net and console | expand |
On 06/11/2023 14:35, David Woodhouse 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 '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 '.. _LABEL-reference-label:' to be emitted when the emitrefs > option is set. > > Signed-off-by: David Woodhouse <dwmw@amazon.co.uk> > --- > docs/sphinx/hxtool.py | 18 +++++++++++++++++- > docs/system/invocation.rst | 1 + > 2 files changed, 18 insertions(+), 1 deletion(-) > Reviewed-by: Paul Durrant <paul@xen.org>
On Mon, 2023-11-06 at 14:35 +0000, David Woodhouse 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 '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 '.. _LABEL-reference-label:' to be emitted when the emitrefs > option is set. > > Signed-off-by: David Woodhouse <dwmw@amazon.co.uk> > --- FWIW I've left this out of the pull request I just sent, and the Xen docs just tell the user to go *find* the -initrd documentation instead of being able to emit a direct link. We can fix that later.
diff --git a/docs/sphinx/hxtool.py b/docs/sphinx/hxtool.py index 9f6b9d87dc..bfb0929573 100644 --- 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 "SRST(label)". + match = re.match(r'SRST\((.*?)\)', line) + if match is None: + serror(file, lnum, "Invalid SRST line") + return match.group(1) + 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 @@ def run(self): serror(hxfile, lnum, 'expected ERST, found SRST') else: state = HxState.RST + if emitrefs and line != "SRST": + label = parse_srst(hxfile, lnum, line) + if label != "": + rstlist.append("", hxfile, lnum - 1) + refline = ".. _" + label + "-reference-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/invocation.rst b/docs/system/invocation.rst index 4ba38fc23d..ef75dad2e2 100644 --- a/docs/system/invocation.rst +++ b/docs/system/invocation.rst @@ -11,6 +11,7 @@ disk_image is a raw hard disk image for IDE hard disk 0. Some targets do not need a disk image. .. hxtool-doc:: qemu-options.hx + :emitrefs: Device URL Syntax ~~~~~~~~~~~~~~~~~