Repository navigation
Docstring section "Other Parameters" not rendering with rest of table #6924
Description
It has been bothering me that in general, kwargs are not very uniform at all in the docs. In many places they are listed after a simple "Addition keyword arguments... : ". Numpydoc does allow for the section Other Parameters (underscored with dashes) but it does not seem to render properly with the Parameters and Returns section table. The Other Parameters section doesn't seem to actually be used in the numpy docs. However, there are several instances of it in mpl/axes/_axes.py.
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.
Activity
jenshnielsen commentedon Aug 8, 2016
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.additional parametersor similarQuLogic commentedon Aug 8, 2016
That's #5743.
[-]Docstring section "Other Parameters" not rendering with rest of tabe[/-][+]Docstring section "Other Parameters" not rendering with rest of table[/+]LindyBalboa commentedon Aug 16, 2016
@QuLogic So is that something that NelleV has taken over or...? Trying to track the progression of that PR has me a little confused.
QuLogic commentedon Sep 9, 2016
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...
tacaswell commentedon Sep 9, 2016
*an extra 11 months
@mdboom and I really thought we could do it in a weekend.....
NelleV commentedon Sep 9, 2016
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.
NelleV commentedon Sep 9, 2016
And I did not take over that PR :)
jenshnielsen commentedon Sep 9, 2016
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.
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
QuLogic commentedon Sep 9, 2016
Napoleon is bundled with Sphinx 1.4+ and implements the NumPyDoc format, so I don't really think it's that non-standard.