Ipywidgets: Cookiecutter based tutorial

[jtpio]

The previous "Custom Widget" has now been removed from the documentation (see https://github.com/jupyter-widgets/ipywidgets/pull/2677), as it was using patterns specific to the classic notebook.

As mentioned in this comment, we could instead have a tutorial based on the TypeScript tutorial, similar to the Let’s Make an Astronomy Picture of the Day JupyterLab Extension.

[jtpio]

cc @ianhi who has been taking some notes on the making of custom widgets: https://github.com/ianhi/custom-ipywidget-howto

Maybe we can incorporate some of these notes in the cookiecutter base tutorial?

Also cc @martinRenou who has been updating the Jupyter Widgets tutorial lately: https://github.com/jupyter-widgets/tutorial

(although the Jupyter Widgets tutorial probably doesn't cover the creation of custom widgets?)

[jtpio]

For reference this is what the current custom widget tutorial looks like (to create widgets in the classic notebook directly):

[martinRenou]

cc @ianhi who has been taking some notes on the making of custom widgets: https://github.com/ianhi/custom-ipywidget-howto
Maybe we can incorporate some of these notes in the cookiecutter base tutorial?

That's a :+1:x9999 for me

Also cc @martinRenou who has been updating the Jupyter Widgets tutorial lately: https://github.com/jupyter-widgets/tutorial
(although the Jupyter Widgets tutorial probably doesn't cover the creation of custom widgets?)

Indeed, we simply mention it and give links to the cookiecutters.

[ianhi]

@jtpio related to this I think fixing images in low level widget docs would be helpful: https://github.com/jupyter-widgets/ipywidgets/issues/2908

Maybe we can incorporate some of these notes in the cookiecutter base tutorial?

:+1: I've had mild ambitions of adding small examples to that - but making those for a cookiecutter tutorial sounds better. It sounds as though you're imagining a single large narrative style tutorial? Something else to consider (perhaps in addition) is having many small (standalone) examples that demonstrate specific things. For example I felt that by focusing only on messages in https://github.com/ianhi/widget_message_speed I learned a lot about messages. Small examples like that that deal with messages, serialization etc in isolation could also be helpful.

[jtpio]

It sounds as though you're imagining a single large narrative style tutorial?

Yes the idea was to replace the one that we removed in a previous PR :)

https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20Custom.html

Something else to consider (perhaps in addition) is having many small (standalone) examples that demonstrate specific things

That sounds like a good idea :+1:

Maybe there could be something similar to the JupyterLab extension examples, but focused on custom widgets instead?

https://github.com/jupyterlab/extension-examples

[ianhi]

Maybe there could be something similar to the JupyterLab extension examples, but focused on custom widgets instead?

That would be awesome. I have multiple times ended up at the widgets-tutorial thinking that it would be just that.

Indeed, we simply mention it and give links to the cookiecutters.

I don't think there's actually a link to the cookiecutter in the readme - might be nice to add that.

Another related thing is that on this page: https://jupyter.org/widgets only the js cookiecutter is linked, probs good to also link the ts cookiecutter

[ianhi]

In addition to a tutorial I think have an official listing of all the methods availiable to both the model and view objects in both typescript and python would be fantastic. I started this in this md file: https://github.com/ianhi/custom-ipywidget-howto/blob/master/available-methods.md but I'm pretty sure that I haven't gotten all of the methods.

[jtpio]

Another related thing is that on this page: https://jupyter.org/widgets only the js cookiecutter is linked, probs good to also link the ts cookiecutter

Good catch :+1:

We would need to modify this page to link to the TS cookiecutter: https://github.com/jupyter/jupyter.github.io/blob/master/widgets.html

edit: opened https://github.com/jupyter/jupyter.github.io/pull/373

In addition to a tutorial I think have an official listing of all the methods availiable to both the model and view objects in both typescript and python would be fantastic

Those could probably be automatically be generated? (api docs / typedoc)

[ianhi]

Those could probably be automatically be generated? (api docs / typedoc)

Would this require the widget docstring comments to be formatted the same way as the backbonejs?

For reference this is what the current custom widget tutorial looks like (to create widgets in the classic notebook directly):

How did you take such a long screenshot????

[jtpio]

Would this require the widget docstring comments to be formatted the same way as the backbonejs?

Not sure about the backbonejs methods yet. Maybe there is a way to reuse the same tooling as in JupyterLab to output API docs like this: https://jupyterlab.github.io/jupyterlab/modules/_coreutils_src_index_.html

How did you take such a long screenshot????

Using Firefox built-in screenshot tool. It's really useful especially for PRs that update the documentation.

[jtpio]

Opened https://github.com/jupyter-widgets/ipywidgets/pull/2919 to start updating the tutorial.

Feedback welcome!

[ianhi]

Those could probably be automatically be generated? (api docs / typedoc)

I took an existing project and ran typedoc on it to. So model1 and one or two of the methods are from me and not from widgets. Not everything has an explanation but this is way better than nothing. So here is my own very long screenshot of the docs:

It's not clear to me where these docs ought to live (and also how to get them to wherever that is). This is maybe a separate concern but I think that the ipywidgets the library of buttons and sliders and the tools for building custom jupyter widgets maybe deserve separate documentation websites? Although it would great to even have docs like the above on the ipywidgets rtd.

[jtpio]

Not everything has an explanation but this is way better than nothing

Thanks @ianhi for the screenshot, It looks like it could indeed already be helpful :+1:

[elliothershberg]

Just wanted to say as a prospective widget developer, having a basic tutorial would be a huge help. I've been able to get the example JS cookie cutter widget working (ran into issues with the TS cookiecutter tests not working, could open an issue in that repo if it would be helpful), but haven't been able to get much farther so far.

I was actually just getting ready to start the custom widget tutorial, and came here after I saw it was removed on latest.

Tangentially, I'm working to use a React component in the frontend, and working off of some discussion here: https://github.com/jupyter-widgets/ipywidgets/issues/2207

Is there any interest in what @jasongrout mentioned about have a cookiecutter or tutorial for using React in ipywidgets?

[elliothershberg]

One other question: is it no longer possible in Jupyter Lab to do this kind of JS execution in a notebook? (from removed tutorial)

It'd be awesome to be able to prototype a widget entirely in a notebook.

[ianhi]

@elliothershberg I feel your pain. I figured things out primarily by looking at existing widgets. In particular I'd recommend looking at ipycanvas, the notes i've collected https://github.com/ianhi/custom-ipywidget-howto, and the jupyter-widgets gitter https://gitter.im/jupyter-widgets/Lobby

Also, per https://github.com/jupyter-widgets/ipywidgets/issues/2908, you should read the notebook source of the low level tutorial https://github.com/jupyter-widgets/ipywidgets/blob/master/docs/source/examples/Widget%20Low%20Level.ipynb

ran into issues with the TS cookiecutter tests not working, could open an issue in that repo if it would be helpful)

The tests have at various times broken but it should still generated working widgets. One other thing to maybe be aware of is that given that jlab3 is around the corner it may be worth your while to work off the jlab3 branch of the cookiecutter.

Tangentially, I'm working to use a React component in the frontend, and working off of some discussion here: #2207

See also https://github.com/ianhi/custom-ipywidget-howto/issues/10

One other question: is it no longer possible in Jupyter Lab to do this kind of JS execution in a notebook? (from removed tutorial)

I don't think that this is possible in jupyterlab. If you want the python side of your widget to be automatically reloaded every time you run a method then you can use autoreload

like so:

%load_ext autoreload
%autoreload 2

import my_widget

[jtpio]

One other question: is it no longer possible in Jupyter Lab to do this kind of JS execution in a notebook? (from removed tutorial)

No, but the new prebuilt (federated) extension system in JupyterLab 3.0 should hopefully improve the workflow on that level (no need to rebuild JupyterLab entirely, just the widget).

[elliothershberg]

@ianhi Nice, thanks for taking the time to compile those resources, and link them here. That definitely gives me a bit to go on.

@jtpio Got it. I'm looking forward to seeing the new extension system! Thanks.

[MicaelJarniac]

The files deleted on #2677 resulted in some broken links (#3061). Once there's an alternative, I believe those links should be updated.