Inconsistent rendering of return/yield value documentation in NumPy-style docstrings

[marvinpfoertner]

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 42

Sphinx 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.0

the 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.html

Expected 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.0

The 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 1

The 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.0

Your 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.

[tk0miya]

I think we have to wait for the discussion in numpy/numpydoc#356 because the name of return value without type (ex. return1 : in test_one_return) is still not valid at this moment. I'd not like to add a Sphinx custom syntax.