sphinx-doc / sphinx-doc/sphinx

sphinx.domains.python.PyXrefMixin.make_xrefs should be consistent with _parse_annotation

Open
#9,641 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domains:py type:enhancement
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):

https://github.com/google/tensorstore/blob/1a59fcb310bc1feb13569f03f7134b4c3a5fa5f4/docs/tensorstore_sphinx_ext/autodoc.py#L76

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":

https://github.com/sphinx-doc/sphinx/blob/ba2439a105e5a68a44dd3f839e86332889cce451/sphinx/domains/python.py#L331

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.