How to automatically add parameter types in sphinx documentation

Question

I am currently trying to implement automatic documentation creation with Sphinx (using the extensions sphinx-apidoc and napoleon). This works quite well, but it would be even better if the typehints (PEP484 convention) are added automatically to the params list.

I was wondering whether this is possible.

More concretely: (from the napoleon example)

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

This renders as follows:

The parameters list has all the parameters, but does not attach the types. It is possible to add them manually, but this might introduce future problems when is decided to change the signature.

Example with manual type addition:

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    """

which renders as:

Traction

This is sphinx we're talking about - if the answer isn't "You have to use this monkeypatch", I'll eat a hat. – Economizer

This issue seems related: github.com/sphinx-doc/sphinx/issues/2738 – Dudeen

The last comment in that issue is exactly what i mean. In the meantime: does some-one know a workaround? – Traction

Answer 1

You can now use the sphinx-autodoc-typehints extension. It will automatically add the types to the sphinx docstrings when you write in the former example above.

To install, just do:

$ pip install sphinx-autodoc-typehints

Add 'sphinx_autodoc_typehints' to the extensions list in conf.py after 'sphinx.ext.napoleon', and make sure you also add napoleon_use_param = True to conf.py.

Windhoek