Python: docstrings and type annotations

Question

Having a function like:

def foo(x: int) -> float:
    return float(x)

I would like to use a NumPy-like docstring like the following:

def foo(x: int) -> float:
    """
    Parameters
    ----------
    x
        Input parameter

    Returns
    -------
    The output value.
    """
    return float(x)

Note that:

• I do not want to specify the parameter type again.
• I do not want to specify the return type again.
• I would like that extension to be able to read the annotated types (and write them in the generated HTML documentation).

Is there a Sphinx extension that supports that? Would you recommend another syntax?

Answer 1

Standard extension is autodoc. Napoleon extension supports Google- and NumPy-style docstrings.