sphinx-doc / sphinx-doc/sphinx

Use aliases in parameter type annotations where they are available

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

Nobody has claimed this yet.

type:enhancement
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.