Reference target not found when combining `~` and `!` prefix

[Viicos]

Describe the bug

Not sure if this is a bug or a feature request, but I'd like to use the~ and ! prefix together, e.g. to have:

:class:`~!typing.TypedDict`

rendered as TypedDict, without the href. With the following configuration:

extensions = ["sphinx.ext.intersphinx"]

nitpicky = True

intersphinx_mapping = {
    "python": ("https://docs.python.org/3/", None),
}

I get the following warning when building:

WARNING: py:class reference target not found: !typing.TypedDict [ref.class]

I'll note that :class:`!~typing.TypedDict` (swapped) does not emit any warning, but is rendered as ~typing.TypedDict.

A Github search shows some usage of this pattern (and I assume they don't use nitpicky, so they don't see the warning).

How to Reproduce

index.rst:

:class:`~!typing.TypedDict`

conf.py:

project = 'test'
copyright = '2025, test'
author = 'test'

extensions = ["sphinx.ext.intersphinx"]

templates_path = ['_templates']
exclude_patterns = []

nitpicky = True

intersphinx_mapping = {
    "python": ("https://docs.python.org/3/", None),
}


html_theme = 'alabaster'
html_static_path = ['_static']

sphinx-build -M html . _build

Environment Information

Platform:              linux; (Linux-6.14.0-27-generic-x86_64-with-glibc2.39)
Python version:        3.13.1 (main, Dec  6 2024, 18:40:43) [Clang 18.1.8 ])
Python implementation: CPython
Sphinx version:        8.2.3
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

sphinx.ext.intersphinx

Additional context

[Viicos]

If this is accepted, happy to propose a patch:

• only allow !~, not ~! (probably makes more sense? We can also allow both)
• document it

[timhoffm]

Allowing both logically makes sense. I suspect it’s an omission that they combination is not supported. I‘d only allow !~.

[jdillard]

Until we arrive at a fix, I made a docs update noting the incompatibility: #14582

I also agree with only allowing !~ in the fix (and documenting it).