sphinx-doc / sphinx-doc/sphinx
sphinx.domains.python.PyXrefMixin.make_xrefs should be consistent with _parse_annotation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Sub-issue split off from #9523.
The tensorstore documentation theme changes sphinx.domains.python.PyXrefMixin.make_xrefs to just use _parse_annotation, so that the formatting of types is the same in both signatures and in the field lists (e.g. "parameters", "return type", "raises" listings):
Currently make_xrefs has a separate implementation, perhaps to accommodate more free-form syntax used in older parameter type specifications before the introduction of type annotations, like "int or float":
I think the older-style "int or float" style should be discourage now that type annotations are so widely used. However, if it is desired to still support them, make_xrefs should still dispatch to _parse_annotations so that real type annotations are displayed consistently.
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 in sphinx/domains/python.py at PyXrefMixin.make_xrefs and _parse_annotation, then compare the tensorstore autodoc.py reference linked in the issue. Determine whether older free-form specifications such as "int or float" remain supported while making real annotations render consistently. Done means the two paths share consistent formatting, with relevant existing behavior preserved.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100