On Thu, May 01, 2025 at 10:31:26AM +0100, Peter Maydell wrote:
> Sphinx requires that labels within documents are unique across the
> whole manual. This is because the "create a hyperlink" directive
> specifies only the name of the label, not a filename+label. Some
> Sphinx versions will warn about duplicate labels, but even if there
> is no warning there is still an ambiguity and no guarantee that the
> hyperlink will be created to the right target.
>
> For QEMU this is awkward, because we have various .rst.inc fragments
> which we include into multiple .rst files. If you define a label in
> the .rst.inc file then it will be a duplicate label. We have mostly
> worked around this by not putting labels into those .rst.inc files,
> or by adding "insert a label" functionality into the hxtool extension
> (see commit 1eeb432a953b0 "doc/sphinx/hxtool.py: add optional label
> argument to SRST directive").
>
> Unfortunately in commit 7f6314427e78 ("docs/devel: add a codebase
> section") we accidentally added a duplicate label, because not all
> Sphinx versions warn about the mistake.
>
> In this case the link was only from the developer docs codebase
> summary, so as the simplest fix for the stable branch, we drop
> the link entirely.
>
> Cc: [email protected]
> Fixes: 1eeb432a953b0 "doc/sphinx/hxtool.py: add optional label argument to
> SRST directive"
> Reported-by: Dario Faggioli <[email protected]>
> Signed-off-by: Peter Maydell <[email protected]>
Acked-by: Eric Blake <[email protected]>
--
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization: qemu.org | libguestfs.org
