| Message ID | 20250501093126.716667-1-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: Don't define duplicate label in qemu-block-drivers.rst.inc | expand |
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: 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> Acked-by: Eric Blake <eblake@redhat.com>
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>
diff --git a/docs/devel/codebase.rst b/docs/devel/codebase.rst index 40273e7d31e..2a3143787a6 100644 --- a/docs/devel/codebase.rst +++ b/docs/devel/codebase.rst @@ -116,7 +116,7 @@ yet, so sometimes the source code is all you have. * `monitor <https://gitlab.com/qemu-project/qemu/-/tree/master/monitor>`_: `Monitor <QEMU monitor>` implementation (HMP & QMP). * `nbd <https://gitlab.com/qemu-project/qemu/-/tree/master/nbd>`_: - QEMU `NBD (Network Block Device) <nbd>` server. + QEMU NBD (Network Block Device) server. * `net <https://gitlab.com/qemu-project/qemu/-/tree/master/net>`_: Network (host) support. * `pc-bios <https://gitlab.com/qemu-project/qemu/-/tree/master/pc-bios>`_: diff --git a/docs/system/qemu-block-drivers.rst.inc b/docs/system/qemu-block-drivers.rst.inc index cfe1acb78ae..384e95ba765 100644 --- a/docs/system/qemu-block-drivers.rst.inc +++ b/docs/system/qemu-block-drivers.rst.inc @@ -500,8 +500,6 @@ What you should *never* do: - expect it to work when loadvm'ing - write to the FAT directory on the host system while accessing it with the guest system -.. _nbd: - NBD access ~~~~~~~~~~
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(-)