DOC updated hexbin documentation to numpydoc format. #7170
Conversation
There was a problem hiding this comment.
Hello,
Thanks for the patch!
There is a bit of work to be done before we can merge it.
- Check that the code is pep8 compliant. Right now, it has whitespace issues (blank line contain whitespace, and there are trailing whitespaces).
- It would be great to add the default of each parameter after the
optionalmention. - I have underlined some issues in the text that need to be addressed for numpydoc to be able to parse the docstring properly.
Thanks a lot for this PR! The docstring is now much more readable.
| Order of scalars is (left, right, bottom, top). | ||
|
|
||
| Other parameters | ||
| ---------------- | ||
| Other keyword arguments controlling color mapping and normalization |
There was a problem hiding this comment.
This line will not be rendered properly by numpydoc. You need to remove it.
|
|
||
| See 8000 also | ||
| -------- | ||
| The standard descriptions of all the |
There was a problem hiding this comment.
The "See Also" section is meant for other functions, methods or modules. This format will not be understood properly by numpdoc.
I think you should be using the "Notes" section instead of the "See Also" section.
It is also possible that the %(Collection)s needs tweaking, but I need to build the documentation to check this.
| @@ -4188,7 +4188,8 @@ def hexbin(self, x, y, C=None, gridsize=100, bins=None, | |||
| sequence of floats, as required by | |||
| :class:`~matplotlib.collections.RegularPolyCollection`. | |||
|
|
|||
| edgecolors : {'none'}, mpl color, color sequence, optional, default is 'none' | |||
| edgecolors : {'none'}, mpl color, color sequence, optional, | |||
| default is 'none' | |||
There was a problem hiding this comment.
Can you indent this line and drop the coma at the end of the previous line? My guess is that sphinx is going to complain about this.
| ---------- | ||
| x : array | ||
| may be masked array, in which case only unmasked points | ||
| will be plotted |
There was a problem hiding this comment.
I would like to see a reduction of the repetition here. I think that for x, y, C you can just say "array or masked array" on the top line. No need to spell out that masked points will be ignored. Or, a note like the original single sentence about masked arrays can be put somewhere.
There was a problem hiding this comment.
@QuLogic has the right suggestion below, applicable here also: group x, y : array or masked array. C needs its own line because it is optional.
| is used. Note if you pass a norm instance, your settings | ||
| for *vmin* will be ignored. | ||
|
|
||
| vmax : scalar, optional, default is *None* |
There was a problem hiding this comment.
You can consolidate: Under vmin, say "see vmax". Under vmax, concisely describe what they do; it is mostly the same, so you can minimize repetition.
There was a problem hiding this comment.
They can be put together as the same entry with vmin, vmax : scalar, ...
| linewidths : scalar, optional, default is *None* | ||
| If *None*, defaults to 1.0. Note that this is a tuple, and | ||
| if you set the linewidths argument you must set it as a | ||
| sequence of floats, as required by |
There was a problem hiding this comment.
This is repeating the original incorrect description. In fact, only a scalar makes sense here, although a sequence can be accepted if it is not too long. I can't see any reasonable use case for a sequence of length other than 1, for which one might as well use a scalar. So, please delete the sentence starting with "Note".
| If *None*, draws the outlines in the default color. | ||
|
|
||
| If a matplotlib color arg or sequence of rgba tuples, draws the | ||
| outlines in the specified color. |
There was a problem hiding this comment.
Again, for hexbin, specifying anything other than a single color makes no sense: first, because one doesn't know at this point where the hexagon getting that edge color will be, and second, because even if one did, it would be nonsensical from a plotting standpoint. So please omit everything having to do with the color sequence.
| If 'log', use a logarithmic scale for the color | ||
| map. Internally, :math:`log_{10}(i+1)` is used to | ||
| determine the hexagon color. | ||
| gridsize : int, optional, default is 100 |
There was a problem hiding this comment.
This should say something like "int, (int, int), optional, default is 100".
|
Thanks! |
[MRG+1] DOC updated hexbin documentation to numpydoc format.
|
backported to v2.x as 1d8435a |
No description provided.