napoleon icon indicating copy to clipboard operation
napoleon copied to clipboard

Multi-line NumPy-style return descriptions without a type get rendered wrong

Open ExplodingCabbage opened this issue 5 years ago • 3 comments

Here's a docstring actually taken from NumPy:

"""
Collect arguments on which to call __array_function__.

Parameters
----------
relevant_args : iterable of array-like
    Iterable of possibly array-like arguments to check for
    __array_function__ methods.

Returns
-------
Sequence of arguments with __array_function__ methods, in the order in
which they should be called.
"""

Napoleon butchers the return description, treating each line as a list item:

image

I don't think there's currently any way at all to get this multi-line return description like this to render correctly using NumPy style.

ExplodingCabbage avatar Aug 11 '19 13:08 ExplodingCabbage

@ExplodingCabbage The | operator should help, shouldn't it?
Here I made some progress: https://github.com/agronholm/sphinx-autodoc-typehints/issues/130, but I lost type hinting.

In your case I think this works (first line is |<space><space>)

Returns
-------
|  
  Sequence of arguments with __array_function__ methods, in the order in 
  which they should be called.

rdbisme avatar Mar 18 '20 18:03 rdbisme

Are there any plans for addressing this? As pointed out above, the workaround using | leaves sphinx-autodoc-typehints broken...

jkochNU avatar Mar 06 '21 15:03 jkochNU

+1 on this. Like @jkochNU I am also patiently awaiting a solution

cthoyt avatar May 08 '21 15:05 cthoyt