Trailing underscores in types
KendrickLamarck opened this issue · comments
Trailing underscores in types in the Parameters
and Returns
sections have to be escaped in order to not give an Unknown target name
warning.
Examples that DON'T work :
def identity(object_):
"""Identity function.
Parameters
----------
object_ : Any
Returns
-------
object_ : type(object_)
Just `object_` again.
"""
return object_
The returns section
Returns
-------
type(object_)
Just `object_` again.
Without a name doesn't work either. In both cases, I have to write type(object\_)
.
I don't know if this is fixable like it was for parameter names (#63). I guess types are actually supposed to be links sometimes, in contrast to parameter names? Feel free to close if that is the case and there's just not really a possible fix.
I think we try to allow / stick with standard RST, and name_
in RST is a link to .. _name: whatever
. So I don't think this is a NumpyDoc issue so much as a RST one
Well, the parameter names also change the default RST behavior by making the names bold. It's just a bit confusing and inconsistent, especially because the types are in italics. This normally also disables linking, but I guess in this case the italicization happens after "link-checking", whereas bolding the parameter names happens before?
But if the intention is to allow standard RST after the :
, that's a good enough reason to close this.