introduce directive for type alias

[joelberkeley-secondmind]

There's no clear way to document a type alias as distinct from a module-level variable

I suggest adding a :type: directive that distinguishes an alias, like

DEFAULT_NUMBER_FACTORY = int
""" :var: zero-argument constructor for default numbers. """

Number = int
""" :type: Type used for numbers. """

def foo(a: Number) -> None:
    ...

It's possible we could use the fact that type aliases aren't meant to have annotations themselves. I'm not sure which is better.

[tk0miya]

At present, PEP-613 (Explicit Type Aliases) has been discussed. So we should follow the spec in the future.

BTW, the PEP will be introduced since python-3.10 or later (maybe). It means we don't have a way to indicate one variable is a kind of type-alias until then. I understand a need for the workaround to do that.

Pros.

• We can indicate a variable is a type-alias.
• We can indicate it before PEP adopted.

Cons.

• Sphinx adopts a non-standard way as a workaround.
• We need to keep backward compatible for a while even after PEP adopted.

[joelberkeley-secondmind]

@tk0miya those are some good points. I assume there will be a desire to keep compatibility with <=3.9 for a long while now, esp since 3.9 isn't released yet. Is it therefore feasible to wait for that PEP?

Can we draw conclusions from sphinx's experience with the :rtype: directive, which is no longer needed with full type hinting in 3.6?

[tk0miya]

Is it therefore feasible to wait for that PEP?

This is the first request for type-alias. So nobody in a hurry now as far as I know. So we can wait for the release of the PEP.

In addition, there are no special representation for type-aliases. So we need to consider how Sphinx represent them in output.

Can we draw conclusions from sphinx's experience with the :rtype: directive, which is no longer needed with full type hinting in 3.6?

If I can design autodoc from scratch now, I'll drop the :rtype: field from spec because it is duplicated with the type annotation. (It might be useful for C extensions. So I can't say I'll surely drop it).

[patrick-nicodemus]

I would like this and I look forward to seeing it in a future release!

It would be great to just click on a custom type alias in the documentation and have it take you to the type definition. It complements the autodoc_type_aliases dictionary well - currently this lets you remove the explicit content of the definition in a place where it adds unnecessary clutter, I am interested in where I will put this explicit definition instead.