numpydoc: Return types without description not displayed correctly

[rkaminsk]

I am using numpydoc style docstrings. But when undocumented return types are used, then the type is displayed as normal text. For example in:

"""
Returns
-------
None
"""

When adding a description, then it is rendered correctly:

"""
Returns
-------
None
    Nothing to return.
"""

I am using pdoc 0.5.4.

[rkaminsk]

I had a look at how this could be fixed. As far as I can see one would have to handle it as a special case similar to what is done with the See Also section. For my purposes, I simply hacked the to_html function in html.mako, which I modified already anyway. If you are interested, I can implement it a little nicer in pdoc and open a pull request.

_re_returns = re.compile(r"^(?<=Returns\n-{7}\n)(?P<type>[^\n]*)(?=(\Z|\n\Z|\n[^ ]))", re.MULTILINE)

def _rep_returns(match):
    return '{}\n    DUMMY DESRIPTION TO REMOVE'.format(match.group('type'))

def to_html(text):
    text = _re_returns.sub(_rep_returns, text)
    text = _to_html(text, module=module, link=link)
    text = text.replace('<dd>DUMMY DESRIPTION TO REMOVE</dd>', '')
    return tex

[kernc]

I, too, thought it probably wouldn't go without special casing. I'd be interested in a solution involving md→md transformation like the one for See Also.

In fact, a Returns section with a single return type without description is not that different from See Also section with a single reference ... 🤔

[rkaminsk]

In fact, a Returns section with a single return type without description is not that different from See Also section with a single reference ...

True. But at first I thought that

"""
Returns
-------
None
    Nothing to return.
"""

is rendered correctly when in fact it is not. None is set like an identifier but it is a type. Right?

[kernc]

Right. 😅