Allow overriding type annotations with docstrings

[suned]

Is your feature request related to a problem? Please describe.
I'm often less than satisfied with the types produced by mkdocstrings. A couple of examples:

When using bound generics. Consider this decorator that preserves the signature of the decorated function:

from typing import Callable, TypeVar

F = TypeVar('F', bound=Callable)

def my_decorator(f: F) -> F:
   ...

When documenting my_decorator the type field in the documentation will simply say F for the argument and return type. This doesn't really give the reader any useful information, but there aren't any other precise ways to type this decorator with the python type system. You could document the type variable as well, but it quickly becomes alot of text for the reader to look at, when really id just like the type of f and the return type of my_decorator to be Callable[..., TypeVar('A')].

When using decorators that alter the signature of a function. Consider this:

def decorator(f: Callable[..., int]) -> Callable[..., Optional[int]]:
    ....

@decorator
def function() -> int:
    ....

The actual return type of function is Optional[int], but if I document it with mkdocstrings the return type will be int, which is simply wrong.

Describe the solution you'd like
I'd like to be able to use the Google docstring type format to manually override the type presented in the docs. To take the last example:

@decorator
def function() -> int:
    """
    Returns:
        Optional[int]: The result
    """
    ...

I'd like mkdocstrings to show Optional[int] as the return type in this case.

Describe alternatives you've considered
Use a type checker to analyze types, and show the analyzed/inferred types instead of the annotated types in the documentation. It would be necessary to allow for different type-checkers in the case where specialized types are used (or e.g a MyPy plugin). This would be a huge feature, and hence I think the suggested solution is better.

Additional context
Add any other context or screenshots about the feature request here.

[pawamoy]

Hi @suned, thanks for the detailed feature request :)

Since pytkdocs already reads type annotations in docstrings, we could consider adding a configuration option like type_source_preference with possible values docstring and annotation.

About the issue in itself: I don't know the typing system enough to formulate a clear opinion. Making pytkdocs smarter about types would be nice, but to me, right now, it seems really complicated. Using a third-party tool like mypy could be more reasonable (I don't want to reinvent the wheel here and make it square :p).

If anyone wants to help here, I'd appreciate it :)

[suned]

we could consider adding a configuration option like type_source_preference with possible values docstring and annotation

That would be cool, but a simple scheme where one takes presedence over the other would also work if thats easier. I can't think of a use-case for using the annotated type over the documented type in cases where both are present. In addition I can report that if you have both a type annotation and a type in the docstring the behaviour is also a little wonky since the documented type ends up in the description.

[suned]

I suppose it would be possible to implement it entirely in a template?

[pawamoy]

I can't think of a use-case for using the annotated type over the documented type in cases where both are present.

Hmmm, you're right. It would make sense to always use the type written in the docstring, even if the parameter/attribute/else is annotated. I think we can safely implement this change.

I suppose it would be possible to implement it entirely in a template?

I don't think so, currently only one of the types (annotation or docstring) is picked up by pytkdocs. You're left with no choice but to use the one it picked in the templates.

[pawamoy]

Done in pytkdocs v0.12

[posita]

For those playing along at home, there seems to be precious little documentation around this feature in pytkdocs that I could find, but perhaps the tests help? (See, e.g., this as well as the release notes.)