sphinx-autodoc-napoleon-typehints

This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of functions. This allows you to use type hints in a very natural fashion, allowing you to migrate from this:

def format_unit(value, unit):
    """
    Formats the given value as a human readable string using the given units.

    :param float|int value: a numeric value
    :param str unit: the unit for the value (kg, m, etc.)
    :rtype: str
    """
    return '{} {}'.format(value, unit)

to this:

from typing import Union

def format_unit(value: Union[float, int], unit: str) -> str:
    """
    Formats the given value as a human readable string using the given units.

    :param value: a numeric value
    :param unit: the unit for the value (kg, m, etc.)
    """
    return '{} {}'.format(value, unit)

There is also support for google docstrings or numpy docstrings with help of the napoleon napoleon sphinx extention. This means that even docstrings like this:

def format_unit_google(self, value: Union[float, int], unit: str, test: Optional[Union[Iterable, str]]) -> str:
    """
    Formats the given value as a human readable string using the given units.

    Args:
        value: a numeric value
        unit: the unit for the value (kg, m, etc.)
        test: bla bla blathe unit for the value (kg, m, etc.)

    Returns:
       This function returns something of
       value: and does not overwrite this part.
    """
    return '{} {}'.format(value, unit)

def format_unit_numpy(self, value: Union[float, int], unit: str, test: Optional[Union[Iterable, str]]) -> str:
    """
    Formats the given value as a human readable string using the given units.

    Parameters
    ----------
    value: a numeric value
    unit: the unit for the value (kg, m, etc.)
    test: bla bla blathe unit for the value (kg, m, etc.)

    Returns
    -------
    This function returns something of
    value: and does not overwrite this part.
    """
    return '{} {}'.format(value, unit)

the result for which is the same as above

$ pip install sphinx-autodoc-napoleon-typehints

extensions = [
    'sphinx.ext.autodoc',
    'sphinx_autodoc_napoleon_typehints'
]