References from autodoc signatures should be resolved via `py:obj` role, not `py:class`

[taminomara]

I have a code base that uses lots of type aliases. Most of them are documented as py:type, and some literal types are documented as py:data. Because of this, references to these objects are not resolved, because python domain uses py:class role to search for them.

I believe that we should use py:obj for all references generated in signatures. I don't see anything that can break if we change current behavior. After all, Python domain doesn't handle objects of different types sharing the same fully-qualified name, so there should be no collisions.

Alternatively, we can make a new role for this (I use lua:_auto in my Lua extension). This will allow easily suppressing nitpicks originating from signatures.

[electric-coder]

For some context, the upcoming Sphinx 8.3.0. indicates a couple of new changes for type aliases:

Changelog
Release 8.3.0 (in development)

#10785: Autodoc: Allow type aliases defined in the project to be properly cross-referenced when used as type annotations. This makes it possible for objects documented as :py:data: to be hyperlinked in function signatures.

#13508: Initial support for PEP 695 type aliases. Patch by Martin Matouš, Jeremy Maitin-Shepard, and Adam Turner.

Before that there was a workaround for some cases documented here #10785 (comment) (can't believe it's been 3 years since I wrote that) but it's troublesome to get right and needs to be carefully maintained manually.

---

I have a code base that uses lots of type aliases.

That makes two of us..! I've shared this ordeal for a number of years now...

I believe that we should use py:obj

Conceptually I'm not sure why a generalization of roles would help (shouldn't roles and types be as specific and narrow as possible?)! We've seen many devs in this repo reporting they go for py:obj whenever they're unwilling to make a distinction, but that will make for spaghetti code (you can't search de .rst code base based on roles) and there have been cases of the more general role not resolving everything correctly. I recall one case of a huge code base written with py:obj everywhere that used autosummary, when eventually a change in one of those declarations happened the error message became obscure because a more specific role hadn't been chosen...