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(-)
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
~~~~~~~~~~~~~~~~~
--
2.34.1