Followup to Conditional HTML Styling

[TomAugspurger]

Follows #10250

For 0.17.1

• Nicer table styling for the pydata.org website
• Include a visual example in 0.17.1.rst
• remove doc/source/html-styling.html and find a way to include doc/source/html-styling.ipynb in the doc build (should use --template=basic)
• update print_versions
• update requirements_all.txt to include jinja

For 0.18.0 / Future

• sparsify MultiIndex repr (maybe push till 0.18)
• easy alignment styles Right align numbers in HTML repr of tables #12144
• Template modification: This is for things like wrapping base64 encoded values in img tags, urls, etc. flows into...
• Break the large template in Styler.template into smaller blocks. Let people extend that. We could (maybe) allow users to choose which template to use to render each column/cell with solving the template modification problem
• Truncated repr
• hook into pd.options, allow setting of default reprs with styles
• Refactor parts of Styler into a BaseStyler, maybe add a LaTeX styler (maybe deprecate / replace the to_html and to_latex methods; Jinja templates are much more pleasant to work with), xref CLN/API: implemented to_html in terms of .style #11700
• Categoricals / Boolens builtin stylings

will add more as we go.

[jreback]

@TomAugspurger I had to slightly change style.rst to get this to appear in the index. You may want to further modify.

[jankatins]

A comment on the API of the highlighter:

def color_negative_red(val):
    """
    Takes a scalar and returns a string with
    the css property `'color: red'` for negative
    strings, black otherwise.
    """
    color = 'red' if val < 0 else 'black'
    return 'color: %s' % color

This basically only works for html representation ("color: red" is css speak) and assumes that the return value should got to the css.

In latex (see e.g. this example), you prefix/suround the value with a command:

[...]
\usepackage[table]{xcolor}% http://ctan.org/pkg/xcolor
  Some & \cellcolor{blue!25}coloured & contents \\

would render the second cell blue (by using a command from a special package).

So for latex you probably need templates ala \cellcolor{blue!25}%s or \textbf{%s} (which make the value bold).

[kynan]

@TomAugspurger I think you made a great start on this! A few ideas for making this approach potentially more flexible:

1. Allow extra attributes on the <table>.

   Common use case: You want to export an html table with sortable column, e.g. using sortable. For that you would need the following opening tag:

   <table class="sortable-theme-bootstrap" data-sortable>
   

2. Support "external" styling via existing custom CSS style sheets.

   For this to work, the current approach with unique ids per cell which are then targeted with a auto generated CSS doesn't really work. Instead it would be useful to be able to assign additional classes (or data attributes) to cells based on the Styler rules.

   Example use case: assign class positive to all values > 0 and negative to all values < 0

   A potential advantage of this would be much smaller size of generated code (since we don't need a custom CSS block for each cell) and better performance when rendering in the browser (fewer rules to apply).

3. Allow setting arbitrary attributes on table cells based on rules.

This extends the previous suggestion and would allow using exported html tables with any kind of JavaScript library using specific attributes.

Sorry for being so late in making these suggestions - I didn't manage to read through all of #10250 before it was merged.

[TomAugspurger]

@kynan fantastic, thanks for the feedback. I'll go through it in more detail later.

Your item 1. sounds pretty simple. Is attribute the correct term for the items in the opening tag? <table class="sortable-theme-bootstrap" data-sortable> We could include a method like .set_table_attributes for that.

[kynan]

@TomAugspurger I believe attribute is the common term and also the one the W3C uses. set_table_attributes sounds sensible to me.

[jreback]

@TomAugspurger merged your PR; I'll leave you to close when you are ready.

[TomAugspurger]

Thanks, I want to get a better solution in place for including notebooks in the sphinx build, but that works for now.

@kynan, for your second item, assigning classes to cells. My current thinking is to have a method on Styler (would it be terrible to call it .classify?) that takes a function to be evaluated and a class to assign to the cells where that function evaluates to True. The limitation here is that the class that's assigned doesn't get to refer to the data. So you couldn't (easily) do something like our .background_gradient, which is why I discarded this approach originally. But it might make sense to have in addition to the one-class-per cell approach we have. This will probably need to wait for the next release though.

[TomAugspurger]

docs are up if anyone sees anything. It does still have the [In] and [Out] tags and ¶ markers I might be able to hide.

[jreback]

@TomAugspurger yep look great!

on the css side, I think its possible if we tag with the SAME names, e.g.

df.style.highlight_null(css='null_class').background_gradient(css='gradients_class')

then as long as you tag THOSE cells with that class it would work. we could have default class names (based on the function name), and have this kw to override.