PR: Port Figure docstrings to numpydoc#9777
Conversation
| ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \ | ||
| 'polar' | 'rectilinear'], optional | ||
| projection : {'aitoff', 'hammer', 'lambert', 'mollweide', \ | ||
| 'polar', 'rectilinear'}, optional |
There was a problem hiding this comment.
Please leave as it was, the new form looks ugly at the terminal / pydoc.
There was a problem hiding this comment.
How about projection : string and then specifying the list of allowed strings underneath?
There was a problem hiding this comment.
Sounds like a better idea I think.
There was a problem hiding this comment.
Specifying the list of allowed strings underneath is reasonable for long lists. I'm still not sure how you want it. Does ugly refer to changed style [ -> { or the indentation. Reverted for now.
| ------ | ||
| axes : Axes | ||
| ------- | ||
| axes : :class:`~.axes.Axes` |
There was a problem hiding this comment.
Types don't need to be marked up (just as you'd write foo : int). Please leave as it was.
There was a problem hiding this comment.
Sometimes sphinx doesn't automatically put in links with out the markup though.
There was a problem hiding this comment.
Suite, I can always strip out unnecessary markup later...
| default value is being ignored. | ||
|
|
||
| facecolor : None or "inherit" or a color spec | ||
| facecolor : None or 'inherit' or a color spec |
There was a problem hiding this comment.
See #8079 re quote style (in fact I prefer double quotes...).
| backend. Most backends support png, pdf, ps, eps and svg. | ||
|
|
||
| *transparent*: | ||
| transparent : {True, False} |
There was a problem hiding this comment.
To clarify, instead of saying {True, False} it's easier to specify that the type has to be bool
There was a problem hiding this comment.
Changed. Thanks for the hint.
| mode : {"expand", None} | ||
| If `mode` is set to ``"expand"`` the legend will be horizontally | ||
| mode : {'expand', None} | ||
| If `mode` is set to ``'expand'`` the legend will be horizontally |
There was a problem hiding this comment.
Please revert all changes up to here. I think what follows looks good.
There was a problem hiding this comment.
This one and similar ones reverted up to here. There were however some plain mistakes above, which lead to broken Sphinx rendering. I did not revert these.
|
Sorry, this is somewhat annoying. Writing documentation isn't the most fun part, but I thought I could give a little help here. But its no use if there are no clear rules. http://matplotlib.org/devdocs/devel/documenting_mpl.html#documenting-matplotlib |
|
Some of this was just "ported" 4 month ago ;-) |
dstansby
left a comment
There was a problem hiding this comment.
Hi @timhoffm thanks for putting together this PR; we're always keen to improve the documentation! Sorry about the confusion in places, our docstring style guides are a bit all over the place at the moment 😢
I've added a couple of suggestions for changes, overall this looks good though. Would it be okay to
- change
{True | False}tobool - where there are a list of strings, put them in the argument description
| backend. Most backends support png, pdf, ps, eps and svg. | ||
|
|
||
| *transparent*: | ||
| transparent : {True, False} |
There was a problem hiding this comment.
To clarify, instead of saying {True, False} it's easier to specify that the type has to be bool
| ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \ | ||
| 'polar' | 'rectilinear'], optional | ||
| projection : {'aitoff', 'hammer', 'lambert', 'mollweide', \ | ||
| 'polar', 'rectilinear'}, optional |
There was a problem hiding this comment.
How about projection : string and then specifying the list of allowed strings underneath?
| ------ | ||
| axes : Axes | ||
| ------- | ||
| axes : :class:`~.axes.Axes` |
There was a problem hiding this comment.
Sometimes sphinx doesn't automatically put in links with out the markup though.
6673184 to
e231fd5
Compare
|
(Will merge if/when tests all pass) |
|
Thanks a lot for your contribution @timhoffm ! |
|
woo TYVM @timhoffm ! |
PR Summary
Fixes
Figure.add_subplot,Figure.add_axesfrom #7205 and some otherFiguredocstrings.