sphinx doc napoleon extension maintainer interest request

[svenevs]

Sphinx is gaining the ability to automatically populate type hints for python code. sphinx-doc/sphinx#7018 will succeed in enabling it for parameters, but there is a hiccup with the Returns clauses. It will be undocumented until Sphinx 3.0. I will be opening an issue on the Sphinx issue tracker to begin discussions about how we can approach fixing things, but we want to be careful not to do anything NumPy would not want done.

The proposed fix introduces a config var that defaults to False (meaning by default, no change) that relaxes the need to annotate the return type in the docstring:

Returns
-------
bool
    Some description of the return type.

will now be allowed to be

Returns
-------
Some description of the return type.

The details of why are described in the comments in the linked PR, but we would like to consolidate discussion to a new sphinx issue.

Are there any specific maintainers that I can CC via an @ mention to guide what we should do how?

Thanks!

[seberg]

Transferred over to numpydoc, I hope this will not mean that the important people miss it, but I expected here some will see it that will not see it at numpy. (if that is wrong, please transfer back).

[rgommers]

@svenevs thanks for asking. Please feel free to Cc me.

First impression: it may be useful for some packages, but I think we would recommend to not do this. The reason is that many users read docstrings in a terminal (e.g. IPython), so reducing the info in the docstring itself and letting Sphinx put it into html docs sounds sub-optimal.

[svenevs]

Thank you for the consideration! Followup-discussion here: sphinx-doc/sphinx#7077

[felix-hilden]

Wouldn't a function with a return type hint have it in the terminal docstring as well?

>>> def foo(param: int) -> int:
        """Docstring."""

>>> help(foo)
foo(param: int) -> int
    Docstring.

Surely even with a Returns section, a reader can easily look at the first line to know what is being returned. Let me know if I've missed some context though.

[pv]

Does that work for C extension functions? I think many wrapper generator tools do not support type hints.

[tristanlatr]

Any chances maintainers can reconsider this proposal ?

Type annotations are becoming more and more popular, the result of that is duplicated return type information, unless, it does not render the docstrings correctly.

But it's probably something to enable on demand for the projects that uses type annotations. At the same time this option should not make it impossible to use regular returns syntax, for exemple for return tuples.

On a technical level, it might be a bit hard to detect if the returns body should be interpreted as free form or if it's a multiple returns as list of <name> : <type like "list of str"> with no description.

[rgommers]

Does that work for C extension functions? I think many wrapper generator tools do not support type hints.

I agree, I'd expect this not to work. C and Cython code typically has a docstring where the signature is manually inserted on the first line. You wouldn't want to duplicate type annotations from a .pyi file for the extension into the docstring manually.

Type annotations are becoming more and more popular, the result of that is duplicated return type information, unless, it does not render the docstrings correctly.

Also keep in mind that type annotations may not match what you want to see in the docs. For existing code bases there's typically Union and Optional all over the place in annotations, and that won't make for nice docs. Also we're trying to introduce specifics like dtype and shape support for array annotations, and those don't belong in the parameters/returns sections.

The more I work with annotations, the worse this idea starts to look to be honest. The Sphinx default of showing annotations in autodoc signatures is also unusable without deferred evaluation of annotations and being consistent about adding well-named aliases for unions.