I agree, In general the docs could use a lot or work and we should be better at settling on a standard for how to format the doc strings.

I guess there are two perhaps solutions to the specific problem of Other Parameters.

• We can probably submit a PR to numpy doc fixing this. Since it's not used in numpy it's probably just a bug.
• Rewrite the docs to not use other parameters. I have cleaned out a few instances where other non numpy doc compatible headers where used. Like additional parameters or similar
• Perhaps switching from numpydoc to sphinx napoleon will fix this. I think there is a pr for that somewhere. But that has it's own issues as far as I remember

Perhaps switching from numpydoc to sphinx napoleon will fix this. I think there is a pr for that somewhere. But that has it's own issues as far as I remember

That's #5743.

@QuLogic So is that something that NelleV has taken over or...? Trying to track the progression of that PR has me a little confused.

Sorry; didn't seem to have replied here. I don't think @NelleV took over, but just accidentally tagged that PR in some commits. Since it's now going in 2.1, I was holding off until 2.0 was out. But of course, that was before 2.0 took an extra 3-4 months...

*an extra 11 months

@mdboom and I really thought we could do it in a weekend.....

I don't think so, and I disagree with the switch from numpydoc to napoleon. I believe that projects should stick to packages that are standard, and napoleon isn't the standard in the scientific python community.
I am also confused with the statement that "Other parameters" is not render properly.

And I did not take over that PR :)

I don't have any strong preference for numpydoc vs napoleon just wanted to make sure that this is coordinated.

The non correct rendering is explained in the original post:
Inspecting the page source makes it a bit more clear.

Looking at the html in a browser inspector, you can see that Parameters and Returns are the
header to a <tr> and the contents are in the respective <td>. However, with Other Parameters,
the contents
are being inserted into a new <tr> following the Other Parameters row.

I.e. here I would expect the gray box to extend all the way down on the left and not across in the other parameters section

Napoleon is bundled with Sphinx 1.4+ and implements the NumPyDoc format, so I don't really think it's that non-standard.