Support PEP 484 type hinting to populate docstrings

jonathansick commented 6 years ago

There are two Sphinx extensions that support PEP 484 type hints for functions parameters:

Although I won't confirm it as the optimal choice, https://github.com/agronholm/sphinx-autodoc-typehints seems to be a more active project.

[Based on my reading](), it seems that these projects are already compatible with tools that parse docstrings. The key is to add the sphinx_autodoc_typehints extension after autodoc, but before a parser like numpydoc or Napoleon.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx_autodoc_typehints',
    'numpydoc'
]

I haven't yet confirmed that numpydoc works, though it should given that Napoleon does work.

kennywlo commented 5 years ago

Hi @jonathansick, has there been any update on this issue? I would like to use type annotations in my DAX API code.

jonathansick commented 5 years ago

I haven't done the work yet on the documentation production side, but there's nothing stopping you from using type annotations in DAX code.

jonathansick commented 5 years ago

See https://jira.lsstcorp.org/browse/DM-17064

jonathansick commented 4 years ago

I had a chance to test sphinx-autodoc-typehints with the Documenteer documentation now that we're using type annotations here. Overall, type annotations aren't yet a full replacement for documented types in docstrings. The main issues are:

Return types aren't described alongside the return description (https://github.com/agronholm/sphinx-autodoc-typehints/issues/75), at least in Numpydoc-formatted docstrings.
Types of fields in dataclasses aren't documented (https://github.com/agronholm/sphinx-autodoc-typehints/issues/44)

Since both sphinx-autodoc-typehints and numpydoc both manipulate docstrings, it's possible that the return type issue could be resolved with more sophisticated post-processing of the docstring.

The following are screenshots of the output for different types of APIs with different versions of the build chain. I looked at numpydoc with sphinx-autodoc-typehints, as well as using Napoleon with sphinx-autodoc-typehints. Numpydoc and Napoleon present parameter slightly differently (definition list versus list). There's no clear advantage to using Napoleon from what I can see here.