mbox series

[0/2] docs: Avoid duplicate labels with a sphinx extn

Message ID 20250429163212.618953-1-peter.maydell@linaro.org
Headers show
Series docs: Avoid duplicate labels with a sphinx extn | expand

Message

Peter Maydell April 29, 2025, 4:32 p.m. UTC 
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 intended 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"). However, we let one into the codebase
without initially noticing, in commit 7f6314427e ("docs/devel: add a
codebase section"), because not all versions of Sphinx warn about
the duplicate labels.

This patchset resolves the problem by implementing a small Sphinx
extension. The extension lets you write in a .rst.inc:

  .. uniquelabel:: mylabel

and it will be as if you had written:

  .. _foo/bar-mylabel

where foo/bar.rst is the top level document that includes the
.rst.inc file.

Patch 1 is the extension; patch 2 is the use of it to fix the
problem in qemu-block-drivers.rst.inc. (Concretely, the result is
that instead of an ambiguous "nbd" label, we now have separate
"system/images-nbd" and "system/qemu-block-drivers-nbd" labels.
We want to link to the former, because the latter is in the
manpage, not the proper HTML manual.)

This patchset is a bit RFC quality -- I have not tested it
super thoroughly, and the extension itself is written based on
our existing ones, because I'm neither a Python nor a Sphinx
expert. I figured I'd send it out to see if people agreed that
it was the right way to solve this problem.

(In theory we could remove the SRST(label) functionality from
the hxtool extension and have the .hx files use uniquelabel.
Not sure that's worthwhile at this point.)

PS: I find that our extensions are confused about whether they
should set "required_arguments = 1" or "required_argument = 1";
probably the latter are all bugs that happen to have no bad
side effects...

thanks
-- PMM

Peter Maydell (2):
  docs: Create a uniquelabel Sphinx extension
  docs: Use uniquelabel in qemu-block-drivers.rst.inc

 docs/conf.py                           |  1 +
 docs/devel/codebase.rst                |  2 +-
 docs/sphinx/uniquelabel.py             | 74 ++++++++++++++++++++++++++
 docs/system/qemu-block-drivers.rst.inc |  2 +-
 4 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 docs/sphinx/uniquelabel.py