sphinx-doc / sphinx-doc/sphinx
[Feature Request] A new role for hyperlink
Open
Nobody has claimed this yet.
domains:py
type:proposal
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
The current role :any: is limited.
- It sometimes not working.
:any:`collections.abc.Iterable` does not work, while :class:`collections.abc.Iterable` works.
It doesn't work in nested types, saylist[int]ordict[str, int] - In the meantime, the hyperlinks in
:type:,:vartype:and:rtype:work very well, but it seems the format of them (italic normal text using em tag) is quite different from cross-reference using:class:or:any:(code tag).
Therefore, I hope sphinx could make a new role to reach the same effect as what we do to get the hyperlink in :type:, :vartype: and :rtype:, and with the same format. This shall help us improve the current napoleon return types when use_rtype=False.
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
Start by tracing how the :any:, :class:, :type:, :vartype:, and :rtype: roles resolve links and render formatting, then inspect the Napoleon return-type handling when use_rtype=False. Done should include a new role that supports the requested type links, including nested types, and matches the existing type-role formatting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100