DOC/API: Styler documentation changes #13225

TomAugspurger · 2016-05-19T01:48:21Z

Update docstring and notebook on output shapes matching
Change build process to use nbconvert to execute the notebook and then convert using NBConvert.

Second commit puts some more restrictions on the output of a user's function passed to .apply.

jreback · 2016-05-19T01:59:17Z

pandas/formats/style.py

-            to the entire DataFrame at once with ``axis=None``.
-        subset: IndexSlice
+            to the entire DataFrame at once with ``axis=None``
+        subset : IndexSlice


I thought we don't have a space before the :

? in general I mean

The examples here do: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections, but I don't think it's enforced, does pandas have a preference?

not sure we are consistent as have seen both ways (or does it even format differently)?

I am wrong - it does specify spaces on both sides
(contrast this to linting which doesn't have s space - but different issue)

yes, it definitly specify spaces on both sides, it's a comment I often give when reviewing docstrings ... :-) (and it is needed to get the html formatting correctly using numpydoc, don't know if napoleon is more flexible)

maybe we should have a commit hook to check this? or lint check or something?

https://gitlab.com/pycqa/flake8-docstrings anyone try?

Last time I looked for something like this, it only checked for pep257, and not for numpydoc specific things

But there seems some discussion/work under way: PyCQA/pydocstyle#129

yes that looks good / we should follow that release

jorisvandenbossche · 2016-05-19T07:55:37Z

@TomAugspurger Did you change a lot in the notebook itself? (Or other phrased: is it worth reviewing? Because online the diff is not shown)

TomAugspurger · 2016-05-19T12:46:28Z

@jorisvandenbossche the notebook changes were

Added:

For Styler.applymap your function should take a scalar and return a single string with the CSS attribute-value pair.
For Styler.apply your function should take a Series or DataFrame (depending on the axis parameter), and return a Series or DataFrame with an identical shape where each value is a string with a CSS attribute-value pair.

and

And crucially the input and output shapes of func must match. If x is the input then func(x).shape == x.shape.

The reason the diff is so big is that I deleted all the output from the notebook committed to the repo.

jreback · 2016-05-19T13:15:47Z

@TomAugspurger what about have a shape check when using .apply? e.g. to guarantee that its the same (or otherwise raise)?

TomAugspurger · 2016-05-19T13:20:56Z

@TomAugspurger what about have a shape check when using .apply

I'll push that change tonight, it's pretty easy, just need tests.

jreback · 2016-05-19T13:24:23Z

gr8! @TomAugspurger better to have an exception than documentation. Further no issues with restricting .apply. No need to make this too general (like DataFrame.apply) that just leads to blind pathways.

TomAugspurger · 2016-05-20T12:16:49Z

Sorry for the delay, pushed changes.

The result of Styler.apply(func, axis=0/1) must have the same shape. The output is from DataFrame.apply, so we know we have a Series with the correct index labels.
The result of Styler.apply(func, axis=None) must be a DataFrame with the same index columns / labels (and so same shape as well).

I put the second one in place to avoid confusing output like

Only the top row gets colored, even though the output was 2x2.

Edit: added a whatsnew.

jreback · 2016-05-26T15:48:05Z

xref: https://travis-ci.org/pydata/pandas/jobs/132906479#L1631

TomAugspurger · 2016-06-16T12:21:20Z

Sorry, forgot this was still open.

Here are the relevant changes to the notebook

Notice that the output shape of highlight_max matches the input shape, an array with len(s) items.

and

When using Styler.apply(func, axis=None), the function must return a DataFrame with the same index and column labels.

and

And crucially the input and output shapes of func must match. If x is the input then func(x).shape == x.shape.

codecov-io · 2016-06-16T16:30:14Z

Current coverage is 84.33%

Merging #13225 into master will increase coverage by <.01%

@@             master     #13225   diff @@
==========================================
  Files           138        138          
  Lines         51068      51080    +12   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits          43065      43080    +15   
+ Misses         8003       8000     -3   
  Partials          0          0

Powered by Codecov. Last updated by b06bc7a...a7ff39c

jreback · 2016-06-16T17:32:51Z

doc/README.rst

@@ -81,7 +81,7 @@ have ``sphinx`` and ``ipython`` installed. `numpydoc
 <https://github.com/numpy/numpydoc>`_ is used to parse the docstrings that
 follow the Numpy Docstring Standard (see above), but you don't need to install
 this because a local copy of ``numpydoc`` is included in the pandas source
-code.
+code. To build the Jupyter notebooks included in the documentation, you'll need `nbconvert <https://nbconvert.readthedocs.io/en/latest/>`_ and `nbformat <http://nbformat.readthedocs.io/en/latest/>`_.


we might also have this same documenation in contributing.rst so update there as well (as well as some info on what deps you need to build the docs)

Maybe we can just include this file in contributing.rst, to not duplicate things (I thought it was done like that before)

jorisvandenbossche · 2016-06-16T18:02:27Z

pandas/formats/style.py

+            result = func(data, **kwargs)
+            if not isinstance(result, pd.DataFrame):
+                raise TypeError("Function {!r} must return a DataFrame when "
+                                "passed to `Styler.apply` with axis=None")


Isn't there a .format(..) missing? (given the {!r})

jorisvandenbossche · 2016-06-16T18:09:43Z

@TomAugspurger Does it build locally for you? (the docs) As on travis there is an error "InputError: [Errno 2] No such file or directory: 'source/html-styling.html'" (not sure if that means that something went wrong ..)

- Update docstring on output shapes matching - Change build process API: Enforce output shape requirements on Styler.apply

TomAugspurger · 2016-06-17T12:44:12Z

Addressed all the comments, thanks. @jorisvandenbossche it does build locally, running from pandas/doc. Is that failure from before this pull request? I'll check this output of this Travis run.

jorisvandenbossche · 2016-06-18T21:26:27Z

Let's see how the travis docs will look like after it is merged.

TomAugspurger added Docs Output-Formatting __repr__ of pandas objects, to_string IO HTML read_html, to_html, Styler.apply, Styler.applymap labels May 19, 2016

jreback reviewed May 19, 2016
View reviewed changes

jreback added this to the 0.18.2 milestone May 19, 2016

TomAugspurger force-pushed the styler-doc branch 2 times, most recently from 4175e4b to 375676d Compare May 20, 2016 12:13

TomAugspurger force-pushed the styler-doc branch 3 times, most recently from 69f91cb to 6b0a9c6 Compare May 20, 2016 12:28

jorisvandenbossche mentioned this pull request May 26, 2016

TST: doc-build and html styling #13295

Closed

TomAugspurger force-pushed the styler-doc branch from 6b0a9c6 to cb28ca4 Compare June 16, 2016 12:17

TomAugspurger changed the title ~~DOC: Styler documentation changes~~ DOC/API: Styler documentation changes Jun 16, 2016

TomAugspurger force-pushed the styler-doc branch from cb28ca4 to 0a06820 Compare June 16, 2016 12:25

jreback reviewed Jun 16, 2016
View reviewed changes

jorisvandenbossche reviewed Jun 16, 2016
View reviewed changes

TomAugspurger added 2 commits June 17, 2016 07:19

DOC: Styler documentation changes

9093df8

- Update docstring on output shapes matching - Change build process API: Enforce output shape requirements on Styler.apply

TST: Additional Styler init and repr tests

3ac4895

TomAugspurger force-pushed the styler-doc branch from 0a06820 to 3ac4895 Compare June 17, 2016 12:20

format error messages

a7ff39c

jorisvandenbossche closed this in 20dd17a Jun 18, 2016

jorisvandenbossche mentioned this pull request Jun 23, 2016

DOC: Include unrendered style notebook in git, execute in build #12521

Closed

TomAugspurger deleted the styler-doc branch April 5, 2017 02:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC/API: Styler documentation changes #13225

DOC/API: Styler documentation changes #13225

TomAugspurger commented May 19, 2016 •

edited by jorisvandenbossche

Loading

jreback May 19, 2016

TomAugspurger May 19, 2016

jreback May 19, 2016

jreback May 19, 2016

jorisvandenbossche May 19, 2016

jreback May 19, 2016

jreback May 19, 2016

jorisvandenbossche May 19, 2016

jorisvandenbossche May 19, 2016

jreback May 19, 2016

jorisvandenbossche commented May 19, 2016

TomAugspurger commented May 19, 2016

jreback commented May 19, 2016 •

edited

Loading

TomAugspurger commented May 19, 2016

jreback commented May 19, 2016

TomAugspurger commented May 20, 2016 •

edited

Loading

jreback commented May 26, 2016

TomAugspurger commented Jun 16, 2016

codecov-io commented Jun 16, 2016 •

edited

Loading

jreback Jun 16, 2016

jorisvandenbossche Jun 16, 2016

jorisvandenbossche Jun 16, 2016

jorisvandenbossche commented Jun 16, 2016

TomAugspurger commented Jun 17, 2016

jorisvandenbossche commented Jun 18, 2016

DOC/API: Styler documentation changes #13225

DOC/API: Styler documentation changes #13225

Conversation

TomAugspurger commented May 19, 2016 • edited by jorisvandenbossche 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche commented May 19, 2016

TomAugspurger commented May 19, 2016

jreback commented May 19, 2016 • edited Loading

TomAugspurger commented May 19, 2016

jreback commented May 19, 2016

TomAugspurger commented May 20, 2016 • edited Loading

jreback commented May 26, 2016

TomAugspurger commented Jun 16, 2016

codecov-io commented Jun 16, 2016 • edited Loading

Current coverage is 84.33%

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche commented Jun 16, 2016

TomAugspurger commented Jun 17, 2016

jorisvandenbossche commented Jun 18, 2016

TomAugspurger commented May 19, 2016 •

edited by jorisvandenbossche

Loading

jreback commented May 19, 2016 •

edited

Loading

TomAugspurger commented May 20, 2016 •

edited

Loading

codecov-io commented Jun 16, 2016 •

edited

Loading