Centralize output widget docs

[pbugnion]

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 Remove large left margin in output widget in docs #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 output widget append_display_data does not display widgets #1811 - that append_display... doesn't work with widgets for right now, instead explicitly use display().

---

This is what the output looks like:

[jasongrout]

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 output widget append_display_data does not display widgets #1811 - that append_display... doesn't work with widgets for right now, instead explicitly use display().

[pbugnion]

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

[maartenbreddels]

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

[jasongrout]

Firefox and Chrome both have facilities for making screenshots of an entire page: https://developer.mozilla.org/en-US/docs/Tools/Taking_screenshots, https://developers.google.com/web/updates/2017/04/devtools-release-notes#screenshots

[pbugnion]

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]

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]

Very nice! Thanks!

[pbugnion]

Great, thanks a lot for the help!