References are now unique across doctree, not doc

[stephenfin]

Describe the bug

In Sphinx 4.4.0 (likely as a result of #9993), we have lost the ability to use reference-style links in docs except where the references are unique. For example, you can no longer use [1] style links.

How to Reproduce

$ cat index.rst

Hello, world
============

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   hello-a
   hello-b

$ cat hello-a.rst

A
=

Lorem ipsum `[1]`_.

_`[1]` Photo of the world: https://en.wikipedia.org/wiki/Earthrise#/media/File:NASA-Apollo8-Dec24-Earthrise.jpg

$ cat hello-b.rst

B
=

Hello, world `[1]`_.

_`[1]` Another world photo: https://en.wikipedia.org/wiki/Earthrise#/media/File:AS8-13-2329.jpg

$ sphinx-build -W -b html . _build/html
Running Sphinx v4.4.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index                                                                          

Warning, treated as error:
/tmp/issue-9993/hello-b.rst:6:duplicate label [1], other instance in /tmp/issue-9993/hello-a.rst

Expected behavior

Documentation should continue to build.

Your project

https://github.com/openstack/nova-specs

Screenshots

No response

OS

Linux

Python version

python3.10

Sphinx version

4.4.0

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[stephenfin]

We're seeing this the openstack/nova-specs project, since we use reference-style ([1]) links quite a lot there. It doesn't seem sane to require these to be unique, IMO.

fwiw, we could in theory fix #9993 by only adding references if they're non-numeric, but that's slightly special behavior and in any case might result in a breaking change.

[tk0miya]

The inline internal target syntax is one of the syntaxes to create a hyperlink target. So I think it's reasonable to behave as block level syntax (.. _label:) does.

On the other hand, it's also understandable that it's like a bug to change the behavior suddenly. So I'd like to add an option to control this behavior and disable it by default during v4.x.

[stephenfin]

The inline internal target syntax is one of the syntaxes to create a hyperlink target. So I think it's reasonable to behave as block level syntax (.. _label:) does.

On the other hand, it's also understandable that it's like a bug to change the behavior suddenly. So I'd like to add an option to control this behavior and disable it by default during v4.x.

This would work, though I would argue that is should remain the default for a long time. This is a big change that breaks multiple previously working documentation trees. The fix is quite invasive also, requiring (in our case) modifying dozens of pages.

I'll post a PR shortly to add the config option.

[stephenfin]

I'll post a PR shortly to add the config option.

I have pushed #10194 to do this.

[stephenfin]

fwiw, I would personally much rather revert this entire thing (i.e. #10178) than make it configurable (i.e. #10194). We have clearly documented the need to specify a title for inline labels for a long time:

Labels that aren’t placed before a section title can still be referenced, but you must give the link an explicit title, using this syntax: :ref:`Link title <label-name>`.

Even ignoring the history here, I don't think this feature is truly useful for larger documentation builds. Because you can't use a proper "format" for the label, the chances of a conflict are really, really high. This is likely the reason why we require users to provide explicit labels for headers, e.g.

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

If this is behind a config option that is always False, I can live with it. I would just like us to think about whether we need yet another config option for an feature that isn't very useful.