numpydoc: Can I omit the type declaration in the docstring when I use type hints?

Question

When using type hints in the function signature, do I need to specify the parameter types in the docstring, too, if I were to comply with numpydoc style?

def add(a: float, b: int) -> float:
    """

    Parameters
    ----------
    a
        Fist number.
    b : int
        Second number.

    Returns
    -------
    float
        Result of a + b

    """
    return a + b

Is the defintion for a in the parameters section sufficient?

Answer 1

At present I think the answer is no if you want to use the numpydoc python package directly. There is an open ticket: https://github.com/numpy/numpydoc/issues/196

I expect any changes will also appear in numpydoc documentation.

However: rendering docstrings written in numpydoc-like type-hinted style might work via other packages. Here's what I've found (partly via that numpydoc issue):

• griffe is a docstring parser that supports this numpydoc-style. That's used by:
  • MkDocs via mkdocstrings
  • quarto via quartodoc (see results-using-type-annotation)
• Sphinx via sphinx-autodoc-typehints