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>
Now that none of our input .hx files have STEXI/ETEXI blocks,
we can remove the code in the Sphinx hxtool extension that
supported parsing them.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200306171749.10756-5-peter.maydell@linaro.org
In hxtool files, section headings defined with the DEFHEADING
and ARCHHEADING macros have a trailing ':'
DEFHEADING(Standard options:)
This is for the benefit of the --help output. For consistency
with the rest of the rST documentation, strip any trailing ':'
when we construct headings with the Sphinx hxtool extension.
This makes the table of contents look neater.
This only affects generation of documentation from qemu-options.hx,
which we will start doing in a later commit.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20200228153619.9906-23-peter.maydell@linaro.org
Some of our documentation includes sections which are created
by assembling fragments of texinfo from a .hx source file into
a .texi file, which is then included from qemu-doc.texi or
qemu-img.texi.
For Sphinx, rather than creating a file to include, the most natural
way to handle this is to have a small custom Sphinx extension which
reads the .hx file and process it. So instead of:
* makefile produces foo.texi from foo.hx
* qemu-doc.texi says '@include foo.texi'
we have:
* qemu-doc.rst says 'hxtool-doc:: foo.hx'
* the Sphinx extension for hxtool has code that runs to handle that
Sphinx directive which reads the .hx file and emits the appropriate
documentation contents
This is pretty much the same way the kerneldoc extension works right
now. It also has the advantage that it should work for third-party
services like readthedocs that expect to build the docs directly with
sphinx rather than by invoking our makefiles.
In this commit we implement the hxtool extension.
Note that syntax errors in the rST fragments will be correctly
reported to the user with the filename and line number within the
hx file.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Message-id: 20200124162606.8787-4-peter.maydell@linaro.org
