Expose type alias instead of actual type

[plannigan]

Is your feature request related to a problem? Please describe. When a type alias is used as part of the function signature, the documentation is generated with the full type information instead of the type alias that was used. I often use type aliases to provide a simple name to a complicated type. For example Callable[[int,str],str]can become MyFunc. I would like the documentation to display the simple name instead of the actual type.

Unfortunately, inspect.signature() automatically resolves type aliases to the actual type. The Sphix project added support of this by allowing the user to pass in a dictionary containing the type names that should be replaced. The project wraps the inspect module so that the resulting Signature can have the desired values for the documentation.

Describe the solution you'd like Using the same process used by Sphix seems like a reasonable solution. It is a bit involved as it requires tracking down all the places where inspect.signature() is used and replacing it with the wrapped version and passing around an additional dictionary in the parse context.

Describe alternatives you've considered A different option would be to handle this at the mkdocstrings layer when the output is generated instead of at the parsing layer, but that feels like not the best place for this specific use case.

[plannigan]

I was looking into this more. With PEP 563, inspect.signature() returns the annotation as a str with the name of the alias instead of a typing._GenericAlias that provides the real type. For now, the PEP can be enabled with from __future__ import annotations, but it becomes the default behavior in 3.10.

This might resolve my immediate need, but I'll have do more experimentation to better understand if there is a difference for enabling it within the project source vs in pytkdocs.

Note: I could see some people keeping the current behavior expose the actual type instead of type alias. This would require using typing.get_type_hints() to evaluate the types. So there might be some work on this in either case to make pytkdocs compatible with 3.10 and beyond.

[pawamoy]

Hello @plannigan, thank you for the additional details. I just wanted to chime in to say that this feature request is acknowledged, I just didn't find time yet to work on it :slightly_smiling_face:

[pawamoy]

This is likely solved by the new handler. Feedback appreciated!