Inconsistent rendering of return/yield value documentation in NumPy-style docstrings #10134
Description
Describe the bug
sphinx.ext.autodoc produces inconsistent output when omitting the return type from NumPy-style return value documentation, even if the correct return type is given as a PEP 484 type hint.
Example (see screenshot):
For the function
def test_one_return() -> int:
"""Test function with one return value.
Returns
-------
return1 :
Description of ``return1``.
"""
return 42Sphinx uses return1 as return type, while for
def test_two_returns() -> tuple[int, float]:
"""Test function with two return values.
Returns
-------
return1 :
Description of ``return1``.
return2 :
Description of ``return2``.
"""
return 42, 42.0the correct return type tuple[int, float] is used.
Moreover, for the function with two return values, Sphinx does not use the PEP 484 type hints in the generated list of return values, but only in the return type field. This happens even if the config option autodoc_typehints = "both" is set.
The output of yield documentation is broken in a similar way. Here, yielding a tuple of two values leads to incosistent output, even when passing the argument types in the docstring.
How to Reproduce
$ git clone https://github.com/marvinpfoertner/sphinx-bug
$ git checkout numpydoc-return-type-bug
$ cd sphinx-bug
$ pip install -r requirements.txt
$ cd docs
$ make html
$ open build/html/index.htmlExpected behavior
The documentation of the functions test_one_return and test_two_returns should render exactly like the documentation of test_one_return_type_in_docstring and test_two_returns_type_in_docstring (see screenshot and code below). However, it should still be possible to overwrite the PEP 484 type hint with the type hint in the docstring.
def test_one_return_type_in_docstring():
"""Test function with one return value and return type documentation in the
docstring.
Returns
-------
return1 : int
Description of ``return1``.
"""
return 42
def test_two_returns_type_in_docstring():
"""Test function with two return values.
Returns
-------
return1 : int
Description of ``return1``.
return2 : float
Description of ``return2``.
"""
return 42, 42.0The documentation of the function test_one_yield should render exactly like the documentation test_one_yield_type_in_docstring.
def test_one_yield() -> Iterator[int]:
"""Test function yielding one value.
Yields
------
yield1 :
Description of ``yield1``.
"""
yield 1
def test_one_yield_type_in_docstring():
"""Test function yielding one value.
Yields
------
yield1 : int
Description of ``yield1``.
"""
yield 1The documentation of the functions test_two_yields and test_two_yields_type_in_docstring should render more like test_two_returns_type_in_docstring, i.e.
- yield1 (int) - Description of
yield1 - yield2 (float) - Description of
yield2
def test_two_yields() -> Iterator[tuple[int, float]]:
"""Test function yielding a tuple of two values.
Yields
------
yield1 :
Description of ``yield1``.
yield2 :
Description of ``yield2``.
"""
yield 1, 2.0
def test_two_yields_type_in_docstring():
"""Test function yielding a tuple of two values.
Yields
------
yield1 : int
Description of ``yield1``.
yield2 : float
Description of ``yield2``.
"""
yield 1, 2.0Your project
https://github.com/marvinpfoertner/sphinx-bug
Screenshots
OS
macOS 12.1
Python version
3.9
Sphinx version
4.4.0
Sphinx extensions
sphinx.ext.autodoc, sphinx.ext.napoleon
Extra tools
No response
Additional context
This is part of numpy/numpydoc#356. See numpy/numpydoc#356 (comment) in particular.
Background:
Specifying the return type twice (once in the type annotation and once in the docstring) is tedious and very error-prone, since the two are almost guaranteed to become inconsistent over time. Since tools like MyPy are available to check PEP 484 docstrings automatically, IMHO PEP 484 type hints should be the preferred source of information, even for the documentation.