Add type annotations to the description instead of signature

[nicoddemus]

This configures Sphinx autodoc to include the type annotations
along with the description of the function/method, instead of including
it into the signature.

Fix #8405

[nicoddemus]

As suggested by @davidism in #8405 (comment).

[bluetech]

As implied in the issue, I'm -0.5 on this -- I think the existing placement makes more sense, but we can improve cases specifically.

[mrbean-bremen]

This looks much better IMHO, but somehow it seems to mess up definitions without type hints.

Old:

New:

Edit: Actually it looks like Sphinx is trying to parse optional parameters as type hints, or something like this.

[nicoddemus]

I guess we should close this then?

As implied in the issue, I'm -0.5 on this -- I think the existing placement makes more sense, but we can improve cases specifically.

Do you have anything in mind?

[nicoddemus]

FTR I think this is much more readable than the current documentation:

Current:

This PR:

Often you look at the docs to get a sense of the parameters... and then each parameter has the full type annotation in the body of the docs. As it is today I have a hard time parsing the signature at all.

[RonnyPfannschmidt]

Currently signatures are absymal in the docs, im +1 even tho i agree with @bluetech on the sentiment

But I prefer readability now over waiting for the solution

Let's make a follow-up issue for beautiful signatures

[nicoddemus]

What do you say @bluetech ?

[bluetech]

1+1-0.5 = 1.5 so seems good to go :)

[nicoddemus]

1+1-0.5 = 1.5 so seems good to go :)

Hehehe thanks!

[pradyunsg]

Actually it looks like Sphinx is trying to parse optional parameters as type hints, or something like this.

It'd be a really good idea to share a minimal example reproducing this issue with Sphinx. This looks like a bug!

[astrojuanlu]

Was the issue with the non typed parameters reported upstream? Couldn't find anything after a quick look.