Repository navigation
Readability of API documentation with type annotations #8405
Description
Activity
- changed the title
[-]Readability of API docstrings with type annotations[/-][+]Readability of API documentation with type annotations[/+]on Mar 5, 2021 You're using the Sphinx autodoc extension, add
autodoc_typehints = "description"todocs/conf.pyto get the hints next to the parameter/return descriptions instead of in the signature.
Reacted by Pradyun Gedam- added a commit that references this issue
on Mar 6, 2021 Thanks for the suggestion! Opened #8407 with this change, let's see what others think.
Tangential: optional[union] doesn't make sense anyway, just add None to the union. That's what happens in runtime anyway iirc
The
_pytest.code.code.ExceptionInfowould hopefully become justExceptionInfoonce we sort out its typing.We can change the
_EtoEorExc; 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.
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
Optionalwhen theNoneis just some dummy default/disable value, andUnion[..., None]when theNoneis 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 swapUnionwith|already somehow.
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.