Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Centralize output widget docs #2020

Merged

Conversation

@pbugnion
Copy link
Member

commented Mar 26, 2018

Addresses issue #1935.

The output widget is powerful since it allows leveraging Jupyter's rich display mechanism. Documentation and recipes for the output widget were scattered across many places in the documentation. This PR tries to centralise mentions of the output widget, and add other contributions previously found in issues and gists.

In particular, we create a new example notebook with:

  • What was previously under the output widget in widget list
  • The section on updating output widgets asynchronously
  • This recipe for creating a logging handler that writes to the output widget
  • This gist with information on clearing the widget output, appending to the widget directly and controlling the output of interact.

Left to do:

  • it looks like there is an extra left margin in your screenshot. Is the output widget not deleting that left margin? (this seems to predate this PR -- I've opened issue #2025 to fix it).
  • The background thread issue is a bit more complicated - threaded output in the ipython kernel isn't cleanly supported, since it's not just scoped to a thread, but also scoped to the execution in the main thread. In other words, if you start a background thread, the background thread output goes into whatever output the main thread happens to be sending things to. What the output widget does is offer a way to redirect that background threaded output to somewhere we choose. We can't rely on the display() mechanism for this since it suffers the problem above. To get around this, we append directly to the output widget, bypassing the ipython display mechanism.
  • in debugging callbacks, "An effective tool for debugging this" - it's not clear what "this" refers to - perhaps a small bit of explanation, or at least just replacing "this"?
  • Can we add a sentence explaining the wait=True argument to the capture decorator?
  • Perhaps a word should be added about #1811 - that append_display... doesn't work with widgets for right now, instead explicitly use display().

This is what the output looks like:

demo3

@pbugnion pbugnion changed the title [WIP] Centralize output widget docs Centralize output widget docs Mar 26, 2018

@jasongrout

This comment has been minimized.

Copy link
Member

commented Mar 26, 2018

Wow, nice! Very nice!!!!

A couple of things:

  1. it looks like there is an extra left margin in your screenshot. Is the output widget not deleting that left margin?
  2. The background thread issue is a bit more complicated - threaded output in the ipython kernel isn't cleanly supported, since it's not just scoped to a thread, but also scoped to the execution in the main thread. In other words, if you start a background thread, the background thread output goes into whatever output the main thread happens to be sending things to. What the output widget does is offer a way to redirect that background threaded output to somewhere we choose. We can't rely on the display() mechanism for this since it suffers the problem above. To get around this, we append directly to the output widget, bypassing the ipython display mechanism.
  3. in debugging callbacks, "An effective tool for debugging this" - it's not clear what "this" refers to - perhaps a small bit of explanation, or at least just replacing "this"?
  4. Can we add a sentence explaining the wait=True argument to the capture decorator?
  5. Perhaps a word should be added about #1811 - that append_display... doesn't work with widgets for right now, instead explicitly use display().

@jasongrout jasongrout added this to the 7.2 milestone Mar 26, 2018

@pbugnion

This comment has been minimized.

Copy link
Member Author

commented Mar 27, 2018

Thanks very much for the feedback! It all makes sense. I'll look into it over the next few days.

@maartenbreddels

This comment has been minimized.

Copy link
Member

commented Mar 28, 2018

great work pascal!
side questions: how do you make a screenshot like the (except on a crazy big monitor in landscape)

@jasongrout

This comment has been minimized.

Copy link
Member

commented Mar 28, 2018

@pbugnion

This comment has been minimized.

Copy link
Member Author

commented Mar 28, 2018

Thanks!

Being able to take whole page screenshots is super useful for docs -- I learnt this from a work colleage. I use a Chrome extension called fireshot, but I'll definitely look into the links Jason posted.

@pbugnion

This comment has been minimized.

Copy link
Member Author

commented Mar 28, 2018

For the extra left margin, I've opened issue #2025 . The error seems to predate this PR: it's already present on docs built off master.

I'm happy to tackle that next, but given that it (presumably) isn't a regression introduced by this PR, and given that merge conflicts in the docs notebooks can be fairly painful, I'd like to do it off a separate branch (so we can merge this as soon as possible).

That aside, I think this PR is ready for another review. I've updated the screenshot with the current version of the documentation.

@jasongrout

This comment has been minimized.

Copy link
Member

commented Mar 29, 2018

Very nice! Thanks!

@jasongrout jasongrout merged commit c0bc4ca into jupyter-widgets:master Mar 29, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@pbugnion pbugnion deleted the pbugnion:centralize-output-widget-docs branch Mar 29, 2018

@pbugnion

This comment has been minimized.

Copy link
Member Author

commented Mar 29, 2018

Great, thanks a lot for the help!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.