search

sphinx-contrib / napoleon

Other
148 stars 48 forks source link

About the return type duplication in Numpy docstring style while using annotations. #35

Open KelSolaar opened 2 years ago

KelSolaar commented 2 years ago

Hi,

The Numpy docstring style while using annotations indicates that the return type must be duplicated in the docstring to comply with the NumPy docstring style.

While I understand the necessity from a docstring parsing standpoint, it seems that the duplication introduce a significant amount of overhead. With that in mind, I'm wondering if it would not make sense to have a custom directive that would make the return type inherit directly from the return annotation or any mechanism that would avoid the duplication.

Cheers,

Thomas

jobrachem commented 2 years ago

Actually, in conjunction with https://github.com/tox-dev/sphinx-autodoc-typehints, I think the only change required would be to add an option similar to napoleon_use_rtype.

Let's take this slightly altered numpy docstring

Returns
-------
Information about the return type

A new option napoleon_omit_rtype = True (default False) could render this to

:returns: Information about the return type

Current behavior, using napolen_use_rtpye=False and napoleon_preprocess_types = False gives

:returns: *Information about the return type*

which always renders the narrative information in italics.

An option napoleon_omit_rtype would immediately improve compatibility to sphinx-autodoc-typehints, which will take care of adding the correct :rtype: based on the type annotations.

twmr commented 2 years ago

@jobrachem May I ask if you have a lokal workaround for this issue, which could be used as long as their is no upstream fix for it?

jobrachem commented 2 years ago

@jobrachem May I ask if you have a lokal workaround for this issue, which could be used as long as their is no upstream fix for it?

Hi @thisch, unfortunately I don’t. At the moment I just accept the italics.

twmr commented 2 years ago

@jobrachem I have a different issue: For me a multi-line string in the Returns section (without a type in the docstring) is converted into a list of single-line bullet points. I guess it should be possible to monkey-patch/fix https://github.com/sphinx-doc/sphinx/blob/f72a25ce7680fde652cbe7e98fd6d1c21b9409b7/sphinx/ext/napoleon/docstring.py#L784 I'll have a look at it in the next days.