sphinx-doc / sphinx-doc/sphinx
References from autodoc signatures should be resolved via `py:obj` role, not `py:class`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Trace how autodoc signatures generate references and how the Python domain resolves the py:class and py:obj roles. Compare the proposed behavior with the linked Lua _auto implementation; done means documented type aliases and literal types resolve from signatures without breaking existing reference behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100