Re: [PULL 00/35] Testing, docs, semihosting and plugin updates

[Peter Maydell]

On Wed, 1 Feb 2023 at 18:07, Alex Bennée <alex.bennee@linaro.org> wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> > I think this is "you can't put labels in qemu-options.hx,
> > because it gets included in two .rst files (invocation.rst
> > and qemu-manpage.rst), and Sphinx complains about the
> > duplicate labels, even though one of the two files is
> > only used in the HTML and one is only used in the manpages".
>
> Oh boo - anyway to work around that because they are helpful links?

Nothing easy. The problem is that Sphinx looks at every .rst
file in the source directory, regardless of whether it's
reachable from the document you specify as the root of the
manual or not. So both lots of .rst files get processed
for both the HTML manual set and the manpages, even though
they don't need to be[*]. This is a long-standing design
deficiency in Sphinx. The only thing I could think of was
splitting the manpages and html docs entirely into separate
subdirectories, and having meson symlink the files which are
actually shared between them. But that seems like quite a lot
of extra machinery.

[*] This shows up for instance in the HTML docs getting a
not-linked-to-from-anywhere HTML version of the qemu(1) manpage:
https://www.qemu.org/docs/master/system/qemu-manpage.html

-- PMM