Re: [PATCH] docs: Don't define duplicate label in qemu-block-drivers.rst.inc

[Pierrick Bouvier <pierrick.bouvier@linaro.org>]

On 5/1/25 2:31 AM, 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: qemu-stable@nongnu.org
> Fixes: 1eeb432a953b0 "doc/sphinx/hxtool.py: add optional label argument to SRST directive"
> Reported-by: Dario Faggioli <dfaggioli@suse.com>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> I have a proposal for how we could permit this link:
>   https://patchew.org/QEMU/20250429163212.618953-1-peter.maydell@linaro.org/
> but since that adds a new Sphinx extension it's a little heavyweight
> to backport to the stable branches, so I thought I'd send out
> this "just drop the link" patch as our fix for stable.
> 
>   docs/devel/codebase.rst                | 2 +-
>   docs/system/qemu-block-drivers.rst.inc | 2 --
>   2 files changed, 1 insertion(+), 3 deletions(-)

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>