We can indicate the types of function parameters using docstring in python:
def f1(a):
"""
:param a: an input.
:type a: int
:return: the input integer.
:rtype: int
"""
return a
For f1, autodoc generates the following document:
fun1(a)
Parameters : a (int) – an input.
Returns : the input integer.
Return type: int
In python 3, the types can be indicated by type hint as well:
def f2(a: int):
"""
:param a: an input.
:return: the input integer.
:rtype: int
"""
return a
When we run autodoc, it puts the type by the parameter declaration, but not in the description:
f2(a: int)
Parameters : a – an input.
Returns : the input integer.
Return type: int
Would it be possible to generate the documentation as f1 using annotation instead of docstring? I'm using python 3.6. Thank you!
Not yet, from what I'm aware Sphinx yet doesn't support this. The bug referenced in a comment was about the representation of the type-hints and not their positioning.
I do know there's currently an extension for Sphinx that takes care of this for you though, called sphinx-autodoc-typehints. You could probably use that for the time being.