The Returns section

[fredrik-1]

What are the expected behavior in the return section when the output variable name is not given?

In the documentation it is written that the variable name is optional and that you can write for example

Returns
--------
int

That is true but the int became bold and for example

Returns
--------
`axes.Axes`

doesn't get formatted into a link and looks ugly.

Is this the intended behavior or is it a bug in matplotlib (that I have worked with) or numpy docs?

Are there any method to get nice formatting in the Returns section without having to came up with an output variable name?

[jnothman]

Sigh. I think this bold may be due to a workaround for a docutils bug related to the inclusion of underscores in parameter or attribute names. I'm not sure how to resolve this in a happy way. I reckon we would avoid many issues if we parsed numpydoc straight to docutils nodes rather than hacking the ReST, but that is probably a whole can of worms.

[fredrik-1]

I found #175. Shouldn't that be a fix for this issue?

[anntzer]

@jnothman I have a long-term todo of rewriting numpydoc to work by parsing the original input into a docutils tree (using the default parser), then do a transform on that tree. At that point it's purely conceptual but would you be interested in such an approach?

[jnothman]

I'd be interested but am not certain that the overhaul is worth the effort

[anntzer]

Bumping it on my todo list...