PR: Port Figure docstrings to numpydoc #9777

timhoffm · 2017-11-14T00:12:51Z

PR Summary

Fixes Figure.add_subplot, Figure.add_axes from #7205 and some other Figure docstrings.

anntzer · 2017-11-14T00:27:09Z

lib/matplotlib/figure.py

-            ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
-'polar' | 'rectilinear'], optional
+        projection : {'aitoff', 'hammer', 'lambert', 'mollweide', \
+        'polar', 'rectilinear'}, optional


Please leave as it was, the new form looks ugly at the terminal / pydoc.

How about projection : string and then specifying the list of allowed strings underneath?

Sounds like a better idea I think.

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.

anntzer · 2017-11-14T00:27:36Z

lib/matplotlib/figure.py

-        ------
-        axes : Axes
+        -------
+        axes : :class:`~.axes.Axes`


Types don't need to be marked up (just as you'd write foo : int). Please leave as it was.

Sometimes sphinx doesn't automatically put in links with out the markup though.

Suite, I can always strip out unnecessary markup later...

anntzer · 2017-11-14T00:28:51Z

lib/matplotlib/figure.py

@@ -1440,22 +1443,22 @@ def legend(self, *args, **kwargs):
            If shadow is activated and framealpha is ``None`` the
            default value is being ignored.

-        facecolor : None or "inherit" or a color spec
+        facecolor : None or 'inherit' or a color spec


See #8079 re quote style (in fact I prefer double quotes...).

anntzer · 2017-11-14T00:29:24Z

lib/matplotlib/figure.py

            One of the file extensions supported by the active
            backend.  Most backends support png, pdf, ps, eps and svg.

-          *transparent*:
+        transparent : {True, False}


To clarify, instead of saying {True, False} it's easier to specify that the type has to be bool

Changed. Thanks for the hint.

anntzer · 2017-11-14T00:30:13Z

lib/matplotlib/figure.py

-        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


Please revert all changes up to here. I think what follows looks good.

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.

timhoffm · 2017-11-14T01:00:01Z

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
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt referenced in #7205
and your comments contradict each other in parts.

anntzer · 2017-11-14T01:10:01Z

#9513 should hopefully clarify some of the rules, and I'm happy to further edit it... but I closed it to wait for another PR to be merged first (because I'd rather resolve conflicts on #9513 rather than the other way round).

jklymak · 2017-11-14T01:12:55Z

Some of this was just "ported" 4 month ago ;-)

#8900

dstansby

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} to bool
where there are a list of strings, put them in the argument description

dstansby · 2017-11-14T14:39:19Z

lib/matplotlib/figure.py

            One of the file extensions supported by the active
            backend.  Most backends support png, pdf, ps, eps and svg.

-          *transparent*:
+        transparent : {True, False}


To clarify, instead of saying {True, False} it's easier to specify that the type has to be bool

dstansby · 2017-11-14T14:40:14Z

lib/matplotlib/figure.py

-            ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
-'polar' | 'rectilinear'], optional
+        projection : {'aitoff', 'hammer', 'lambert', 'mollweide', \
+        'polar', 'rectilinear'}, optional


How about projection : string and then specifying the list of allowed strings underneath?

dstansby · 2017-11-14T14:40:48Z

lib/matplotlib/figure.py

-        ------
-        axes : Axes
+        -------
+        axes : :class:`~.axes.Axes`


Sometimes sphinx doesn't automatically put in links with out the markup though.

dstansby

Thanks a lot!

dstansby · 2017-11-14T22:30:45Z

(Will merge if/when tests all pass)

NelleV · 2017-11-15T05:10:23Z

Thanks a lot for your contribution @timhoffm !

choldgraf · 2017-11-15T15:12:15Z

woo TYVM @timhoffm !

anntzer reviewed Nov 14, 2017

View reviewed changes

dstansby added the Documentation label Nov 14, 2017

dstansby reviewed Nov 14, 2017

View reviewed changes

port some figure docstrings to numpydoc

e231fd5

timhoffm force-pushed the figure-docstrings branch from 6673184 to e231fd5 Compare November 14, 2017 22:16

dstansby approved these changes Nov 14, 2017

View reviewed changes

timhoffm mentioned this pull request Nov 14, 2017

Consistent Documentation Guide for Docstrings #9786

Closed

6 tasks

NelleV merged commit 5ec960b into matplotlib:v2.1.x Nov 15, 2017

QuLogic added this to the v2.1.1 milestone Nov 15, 2017

timhoffm deleted the figure-docstrings branch November 28, 2017 20:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PR: Port Figure docstrings to numpydoc #9777

PR: Port Figure docstrings to numpydoc #9777

timhoffm commented Nov 14, 2017

anntzer Nov 14, 2017

dstansby Nov 14, 2017

anntzer Nov 14, 2017

timhoffm Nov 14, 2017

anntzer Nov 14, 2017

dstansby Nov 14, 2017

anntzer Nov 14, 2017

timhoffm Nov 14, 2017

anntzer Nov 14, 2017 •

edited

Loading

timhoffm Nov 14, 2017

anntzer Nov 14, 2017

dstansby Nov 14, 2017

timhoffm Nov 14, 2017

anntzer Nov 14, 2017

timhoffm Nov 14, 2017

timhoffm commented Nov 14, 2017

anntzer commented Nov 14, 2017

jklymak commented Nov 14, 2017 •

edited

Loading

dstansby left a comment

dstansby Nov 14, 2017

dstansby Nov 14, 2017

dstansby Nov 14, 2017

dstansby left a comment

dstansby commented Nov 14, 2017

NelleV commented Nov 15, 2017

choldgraf commented Nov 15, 2017

PR: Port Figure docstrings to numpydoc #9777

PR: Port Figure docstrings to numpydoc #9777

Conversation

timhoffm commented Nov 14, 2017

PR Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anntzer Nov 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm commented Nov 14, 2017

anntzer commented Nov 14, 2017

jklymak commented Nov 14, 2017 • edited Loading

dstansby left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dstansby left a comment

Choose a reason for hiding this comment

dstansby commented Nov 14, 2017

NelleV commented Nov 15, 2017

choldgraf commented Nov 15, 2017

anntzer Nov 14, 2017 •

edited

Loading

jklymak commented Nov 14, 2017 •

edited

Loading