Readability of API documentation with type annotations

[nicoddemus]

Hey folks,

Recently on twitter a thread about type annotations in documentation gained traction, using pytest as an example:

I'm opening this to see if we can improve the situation.

[davidism]

You're using the Sphinx autodoc extension, add autodoc_typehints = "description" to docs/conf.py to get the hints next to the parameter/return descriptions instead of in the signature.

[nicoddemus]

Thanks for the suggestion! Opened #8407 with this change, let's see what others think.

[Tinche]

Tangential: optional[union] doesn't make sense anyway, just add None to the union. That's what happens in runtime anyway iirc

[bluetech]

The _pytest.code.code.ExceptionInfo would hopefully become just ExceptionInfo once we sort out its typing.

We can change the _E to E or Exc; I suppose legibility is more important here than the privacy designation.

Other than that it looks good to me for an API reference. Maybe some syntax highlighting would help, but that's up to Sphinx.

[bluetech]

Tangential: optional[union] doesn't make sense anyway, just add None to the union. That's what happens in runtime anyway iirc

I myself at least prefer to use Optional when the None is just some dummy default/disable value, and Union[..., None] when the None is an actual "legitimate" value (e.g. JsonPrimitive = Union[str, float, bool, None]). Although the new | syntax will make this moot.

Speaking of |, it would also make this a little clearer display wise. Maybe Sphinx can swap Union with | already somehow.