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:

This is sphinx we're talking about - if the answer isn't "You have to use this monkeypatch", I'll eat a hat. — Aran-Fey
– Aran-Fey, Commented Mar 28, 2018 at 17:39
This issue seems related: github.com/sphinx-doc/sphinx/issues/2738 — mzjn
– mzjn, Commented Mar 28, 2018 at 17:55
The last comment in that issue is exactly what i mean. In the meantime: does some-one know a workaround? — Matthijs
– Matthijs, Commented Mar 28, 2018 at 18:11

MSeifert · Accepted Answer · 2019-06-09 16:18:31Z

16

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.

edited Jun 9, 2019 at 16:18

MSeifert

154k41 gold badges356 silver badges377 bronze badges

answered Jul 12, 2018 at 18:42

Kyle Barron

2,7091 gold badge24 silver badges18 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Jon Nordby Jan 19 at 11:44

I think the project link should be github.com/tox-dev/sphinx-autodoc-typehints

Collectives™ on Stack Overflow

How to automatically add parameter types in sphinx documentation

1 Answer 1

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related