DOC/API: Styler documentation changes
State: closed

Closes https://github.com/pydata/pandas/issues/13222, #13225
- 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`.


Labels:
name: Docs
name: Output-Formatting
description: __repr__ of pandas objects, to_string
name: IO HTML
description: read_html, to_html, Styler.apply, Styler.applymap

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

@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.

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

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

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

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.

Sorry for the delay, pushed changes.
1. 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.
2. 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

![screen shot 2016-05-20 at 7 14 39 am](https://cloud.githubusercontent.com/assets/1312546/15427414/8a2b50ee-1e5a-11e6-83ed-b28ee517d991.png)

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

Edit: added a whatsnew.

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

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`.

## [Current coverage](https://codecov.io/gh/pydata/pandas/pull/13225?src=pr) is **84.33%**

> Merging [#13225](https://codecov.io/gh/pydata/pandas/pull/13225?src=pr) into [master](https://codecov.io/gh/pydata/pandas/branch/master?src=pr) will increase coverage by **<.01%**

``` diff
@@             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](https://codecov.io?src=pr). Last updated by [b06bc7a...a7ff39c](https://codecov.io/gh/pydata/pandas/compare/b06bc7ab10552079b5300f53ae9458b5b1583402...a7ff39cb85875c5069e0c118bac8b6791eefccc1)

@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 ..)

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.

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