search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.42k stars 2.09k forks source link

Napoleon: Enable numpydoc “Returns” section without type #5887

Open flying-sheep opened 5 years ago

flying-sheep commented 5 years ago

I use sphinx-autodoc-typehints, but can’t seem to find a way to write a Returns section in numpydoc style that doesn’t result in a :rtype: being inserted.

name
    Desc

… results in “name” being treated as type

name: _
    Desc

… results in “” being treated as type. Leaving out the “” just results in “name” being treated as type again.

Desc

… results in an empty description and “Desc” being used as return type.

flying-sheep commented 5 years ago

Honestly, I’d just like napoleon to treat the returns section as free form, and only if there’s a rigorous definition list structure, napoleon should do its magic there.

Most functions return just a single value, and it should be possible to just write a description there and have it render as a plain paragraph.

Returns
=======
Foo bar baz

↓

… …
Returns: Foo bar baz 
Returns
=======
Foo
    Bar baz

↓

… …
Returns:
Foo
Bar baz
 
Returns
=======
foo: Bar
    baz

↓

… …
Returns:
foo : Bar
Baz
znicholls commented 5 years ago

This would be great for us too!