Support PEP 484 type hinting to populate docstrings

[jonathansick]

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

• https://github.com/agronholm/sphinx-autodoc-typehints
• https://github.com/nicolashainaux/sphinx-autodoc-annotation

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]

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

[jonathansick]

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]

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

[jonathansick]

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.

Typed function

numpydoc with sphinx-autodoc-typehints. Notice how the return type is on a separate line from the return description.

numpydoc without sphinx-autodoc-typehints.

napoleon with sphinx-autodoc-typehints.

Data class

numpydoc with sphinx-autodoc-typehints.

napoleon with sphinx-autodoc-typehints.

Function without type annotations

numpydoc with sphinx-autodoc-typehints.

numpydoc without sphinx-autodoc-typehints.

napoleon with sphinx-autodoc-typehints

napoleon without sphinx-autodoc-typehints