sphinx-contrib / napoleon

Other
149 stars 48 forks source link

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

Open ExplodingCabbage opened 5 years ago

ExplodingCabbage commented 5 years ago

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.

rdbisme commented 4 years ago

@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.
jkochNU commented 3 years ago

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

cthoyt commented 3 years ago

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