sphinx-doc / sphinx-doc/sphinx
Use aliases in parameter type annotations where they are available
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
Callable definitions discovered by autodoc end up being hard to read as type annotations are unpacked in
full, even when they have succinct aliases available or have been expressed in shorter forms.
For example, this code:
from sybil.typing import Evaluator
class CodeBlockParser:
def __init__(self, language: str = None, evaluator: Evaluator = None):
...
...ends up being rendered by Sphinx as:
class sybil.parsers.codeblock.CodeBlockParser(language: Optional[str] = None,
evaluator: Optional[Callable[[sybil.example.Example], Optional[str]]] = None)
Describe the solution you'd like
Where I have:
.. automodule:: sybil.typing
:members:
.. automodule:: sybil.parsers.codeblock
:members:
I think it would be much clearer and easier to read to render the class definition as:
class sybil.parsers.codeblock.CodeBlockParser(language: str = None, evaluator: Evaluator = None)
With "Evaluator" being link to the alias definition.
Describe alternatives you've considered
The other thing that might be important for Sphinx to do, is when these lines get long, which is now a frequent occurrence with type annotations, the html generated should make it easier for themes to show these as:
class sybil.parsers.codeblock.CodeBlockParser(
language: str = None,
evaluator: Evaluator = None
)
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
Reproduce the example using the sybil.typing and sybil.parsers.codeblock automodule directives, then trace how autodoc renders callable signatures and type annotations. Done means available aliases such as Evaluator are shown as readable links instead of expanded types, with long signatures structured so themes can wrap them clearly.
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