Inconsistent documentation of type of _css for new widgets

[bgschaid]

In the migration guide for the new widgets http://ipython.org/ipython-doc/3/whatsnew/version3_widget_migration.html it says "use the _css dictionary to set CSS styling like set_css and get_css". But it seems to me that _css is actually a tuple. This is consistent with #6235 (comment) in the pull request where it says "_css tuple remains"

At least I'd suggest to change the migration guide as this raises unjustified hopes that the migration of small css-changes (in my case setting the width of checkbox-labels) might be painless

[jdfreder]

Hey @bgschaid ,

I'm glad you opened the issue. @SylvainCorlay has also experienced a lot of pain because of this change. A quick fix is to use the 2.x set_css method, replacing self with widget:

def set_css(widget, dict_or_key, value=None, selector=''):
    """Set one or more CSS properties of the widget.
    This function has two signatures:
    - set_css(css_dict, selector='')
    - set_css(key, value, selector='')
    Parameters
    ----------
    widget: Widget
    css_dict : dict
        CSS key/value pairs to apply
    key: unicode
        CSS key
    value:
        CSS value
    selector: unicode (optional, kwarg only)
        JQuery selector to use to apply the CSS key/value.  If no selector 
        is provided, an empty selector is used.  An empty selector makes the 
        front-end try to apply the css to a default element.  The default
        element is an attribute unique to each view, which is a DOM element
        of the view that should be styled with common CSS (see 
        `$el_to_style` in the Javascript code).
    """
    if not selector in widget._css:
        widget._css[selector] = {}
    my_css = widget._css[selector]

    if value is None:
        css_dict = dict_or_key
    else:
        css_dict = {dict_or_key: value}

    for (key, value) in css_dict.items():
        if not (key in my_css and value == my_css[key]):
            my_css[key] = value
    widget.send_state('_css')

As a long term fix, maybe we can readdress the decision to remove set/get_css, @ellisonbg @jasongrout.

[bgschaid]

Thanks. But it doesn't work for me. widget._css is a tuple and therefor assigning to widget._css[selector] fails. And I didn't go through the code to see what "formatting" the data in the tuple requires.

Having a set_css would be cool (if it isn't a technical problem) but as an immediate fix I'd suggest to modify the migration-guide (it is OK if stuff disappears from the API, but at least it should be correctly documented)

[jdfreder]

Oh, that's right, I forgot that we had changed that! I guess the migration doc is shows that confusion :P

[jdfreder]

I'm not sure how I can change the document http://ipython.org/ipython-doc/3/whatsnew/version3_widget_migration.html - since it's in the archives. @minrk @Carreau may I change it by hand directly? Or do I change it here, backport the fix, and rebuilt the website docs?

[jdfreder]

... There's a wiki equivalent here, which has been updated with the correct information. Does that suffice? If so, let's close this issue.

[Carreau]

I have no objection in rebuilding the docs, one of the things I'm working on is having a "warning old docs" at the top of all pages, but I can't achieve to rebuild all the docs correctly.

[jdfreder]

Maybe, anticipating problems like this in the future, it would make more sense for me to link to the wiki in the docs. What do you think?

[Carreau]

Closing as this issue is not in IPython itself and if still problematic and relevant should be opened on the right repository. This will allow to keep the number of opened issue on the IPython repo under control.

Feel free to keep commenting or reopen if necessary.

Thanks.