DOC: document optional arguments on plot submethods #27381

hancar · 2019-07-13T15:46:44Z

closes DOC: document optional arguments on plot submethods #11042
passes black pandas
Signatures and doc strings for plot sub-methods opt-args added.

jbrockmendel · 2019-07-14T04:23:23Z

Is there an issue for this?

hancar · 2019-07-14T09:17:28Z

Is there an issue for this

WillAyd

Rather than copy / paste this can you use the Appender decorator that we use for other docstrings? You can see a use of this in pandas.core.generic amongst other places

WillAyd · 2019-08-26T18:23:18Z

@hancar can you fix up merge conflicts and address comment above?

hancar · 2019-08-27T08:12:11Z

@hancar can you fix up merge conflicts and address comment above?

Oh, thank you for reminding, today I will find some time.

pep8speaks · 2019-09-01T16:05:06Z

Hello @hancar! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

In the file pandas/plotting/_core.py:

Line 1336:89: E501 line too long (89 > 88 characters)
Line 1558:89: E501 line too long (89 > 88 characters)

Comment last updated at 2019-11-19 08:22:52 UTC

TomAugspurger · 2019-09-03T15:29:40Z

Seems like some test and code checks are failing. Let us know if you need help looking into them.

hancar · 2019-10-14T22:30:24Z

Seems like some test and code checks are failing. Let us know if you need help looking into them.

Yes please, now I would really appreciate some help. It seems like the tests fail on some linting or docstring validation, but I didn't manage to rerun the tests locally to find the problem. This is from Checks/12_Testing docstring validation script.txt in the logs:

2019-10-10T22:31:39.8687326Z scripts/tests/test_validate_docstrings.py ..............................................x..x..............................................docstring1: err desc
2019-10-10T22:31:39.8688602Z docstring1: err desc
2019-10-10T22:31:39.8689131Z docstring1: err desc
2019-10-10T22:31:39.8689537Z docstring2: err desc
2019-10-10T22:31:39.8689947Z docstring2: err desc
2019-10-10T22:31:39.8717964Z ..EXECUTED
2019-10-10T22:31:39.8732189Z {"docstring1": {"errors": [["ER01", "err desc"], ["ER02", "err desc"], ["ER03", "err desc"]]}, "docstring2": {"errors": [["ER04", "err desc"], ["ER05", "err desc"]]}}.Series.foo: err desc
2019-10-10T22:31:39.8732941Z DataFrame.bar: err desc
2019-10-10T22:31:39.8733428Z Series.foobar: err desc
2019-10-10T22:31:39.8733849Z Series.foo: err desc
2019-10-10T22:31:39.8746350Z .

Can you give me some hint, please?

WillAyd

doesn't look like CI logs are available any more so not sure on error; you can of course run scripts/validate_docstrings.py locally which will likely give you more info

WillAyd · 2019-10-22T01:56:19Z

pandas/plotting/_core.py

@@ -588,7 +607,7 @@ class PlotAccessor(PandasObject):
        labels with "(right)" in the legend
    include_bool : bool, default is False
        If True, boolean values can be plotted.
-    **kwargs
+    `**kwargs` : keywords


Shouldn't need the backticks here

WillAyd

I think this is a nice PR. Let's see if we can fix up a bit and get this in

WillAyd · 2019-11-07T23:59:04Z

pandas/plotting/_core.py

@@ -588,7 +607,7 @@ class PlotAccessor(PandasObject):
        labels with "(right)" in the legend
    include_bool : bool, default is False
        If True, boolean values can be plotted.
-    **kwargs
+    **kwargs : keywords


I think you can revert this; shouldn't be necessary for args / kwargs

WillAyd · 2019-11-08T00:00:04Z

pandas/plotting/_core.py

@@ -1051,7 +1084,8 @@ def box(self, by=None, **kwargs):
        ----------
        by : str or sequence
            Column in the DataFrame to group by.
-        **kwargs
+        %s
+        **kwargs : optional


same comment on kwargs

WillAyd · 2019-11-08T00:00:57Z

pandas/plotting/_core.py


-    def bar(self, x=None, y=None, **kwargs):
-        """
+    @Appender(_line_docs % _shared_docs)


Rather than putting this all in Appender you can use Appender with Substitution decorators. Check pandas.core.frame for pre-existing examples

Just to be sure: do you mean to replace

@Appender(_line_docs % _shared_docs)

by

@Substitution(_shared_docs) @Appender(_line_docs)

???

For me this is just more decorators making the code more complex, but not really nicer. Even in pandas.core.frame there are counter examples:

@Appender(_shared_docs["align"] % _shared_doc_kwargs)

So, do we really want that many decorators?

OK sure. Looks like some CI failures can you merge master and we can get this one in

WillAyd · 2019-11-08T00:01:58Z

pandas/plotting/_core.py

-    def bar(self, x=None, y=None, **kwargs):
-        """
+    @Appender(_line_docs % _shared_docs)
+    def line(self, x=None, y=None, figsize=None, subplots=False, sharex=None,


While doing this you might as well make all of the new keywords "keyword only", i.e. don't allow them to be called positionally. Easier to do now than to try and go back and do it later

alimcmaster1 · 2019-11-17T16:36:23Z

Thanks for the PR @hancar - mind merging master and addressing @WillAyd comments whenever you have time- thanks!

WillAyd · 2019-12-17T18:00:42Z

@hancar looks like some CI issues can you take a look?

datapythonista · 2019-12-29T13:57:54Z

Closing as stale, @hancar if you want to finish this, please let us know to reopen.

hancar force-pushed the document.opt.arguments.on.plot.submethods branch 2 times, most recently from 2a80564 to a0bdf0b Compare July 14, 2019 14:43

WillAyd changed the title ~~#11042 formatting~~ DOC: document optional arguments on plot submethods Jul 15, 2019

WillAyd added the Docs label Jul 15, 2019

WillAyd requested changes Jul 15, 2019

View reviewed changes

hancar force-pushed the document.opt.arguments.on.plot.submethods branch from a0bdf0b to 78c9620 Compare September 1, 2019 16:05

hancar force-pushed the document.opt.arguments.on.plot.submethods branch from 78c9620 to 83051d5 Compare September 1, 2019 16:21

hancar force-pushed the document.opt.arguments.on.plot.submethods branch 3 times, most recently from 34adc6c to f0c41a0 Compare September 6, 2019 00:29

hancar force-pushed the document.opt.arguments.on.plot.submethods branch from f0c41a0 to 6d85054 Compare September 15, 2019 20:45

hancar force-pushed the document.opt.arguments.on.plot.submethods branch 8 times, most recently from 9a2f226 to d1a843b Compare October 10, 2019 22:10

WillAyd requested changes Oct 22, 2019

View reviewed changes

hancar force-pushed the document.opt.arguments.on.plot.submethods branch from d1a843b to 50bba72 Compare October 22, 2019 05:57

WillAyd requested changes Nov 8, 2019

View reviewed changes

Hancar, Pavel added 2 commits November 19, 2019 09:12

11042 refactor(plot sub-methods): signatures

572751a

11042 refactor(plot sub-methods): req. changes 2

002fc51

hancar force-pushed the document.opt.arguments.on.plot.submethods branch from 50bba72 to 002fc51 Compare November 19, 2019 08:22

datapythonista closed this Dec 29, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: document optional arguments on plot submethods #27381

DOC: document optional arguments on plot submethods #27381

hancar commented Jul 13, 2019 •

edited by WillAyd

Loading

jbrockmendel commented Jul 14, 2019

hancar commented Jul 14, 2019

WillAyd left a comment

WillAyd commented Aug 26, 2019

hancar commented Aug 27, 2019

pep8speaks commented Sep 1, 2019 •

edited

Loading

TomAugspurger commented Sep 3, 2019

hancar commented Oct 14, 2019 •

edited

Loading

WillAyd left a comment

WillAyd Oct 22, 2019

WillAyd left a comment

WillAyd Nov 7, 2019

WillAyd Nov 8, 2019

WillAyd Nov 8, 2019

hancar Nov 19, 2019

WillAyd Nov 23, 2019

WillAyd Nov 8, 2019

alimcmaster1 commented Nov 17, 2019

WillAyd commented Dec 17, 2019

datapythonista commented Dec 29, 2019

DOC: document optional arguments on plot submethods #27381

DOC: document optional arguments on plot submethods #27381

Conversation

hancar commented Jul 13, 2019 • edited by WillAyd Loading

jbrockmendel commented Jul 14, 2019

hancar commented Jul 14, 2019

WillAyd left a comment

Choose a reason for hiding this comment

WillAyd commented Aug 26, 2019

hancar commented Aug 27, 2019

pep8speaks commented Sep 1, 2019 • edited Loading

Comment last updated at 2019-11-19 08:22:52 UTC

TomAugspurger commented Sep 3, 2019

hancar commented Oct 14, 2019 • edited Loading

WillAyd left a comment

Choose a reason for hiding this comment

WillAyd Oct 22, 2019

Choose a reason for hiding this comment

WillAyd left a comment

Choose a reason for hiding this comment

WillAyd Nov 7, 2019

Choose a reason for hiding this comment

WillAyd Nov 8, 2019

Choose a reason for hiding this comment

WillAyd Nov 8, 2019

Choose a reason for hiding this comment

hancar Nov 19, 2019

Choose a reason for hiding this comment

WillAyd Nov 23, 2019

Choose a reason for hiding this comment

WillAyd Nov 8, 2019

Choose a reason for hiding this comment

alimcmaster1 commented Nov 17, 2019

WillAyd commented Dec 17, 2019

datapythonista commented Dec 29, 2019

hancar commented Jul 13, 2019 •

edited by WillAyd

Loading

pep8speaks commented Sep 1, 2019 •

edited

Loading

hancar commented Oct 14, 2019 •

edited

Loading