Repository: bokeh/bokeh

Issue:
notebook comms and push_notebook docs are not up to date.



Discussion:

Resolving patch:
diff --git a/bokeh/io.py b/bokeh/io.py
--- a/bokeh/io.py
+++ b/bokeh/io.py
@@ -294,10 +294,11 @@ def show(obj, browser=None, new="tab", notebook_handle=False):
 
         notebook_handle (bool, optional): create notebook interaction handle (default: False)
             For notebook output, toggles whether a handle which can be
-            used with``push_notebook`` is returned.
+            used with ``push_notebook`` is returned.
+
     Returns:
         when in a jupyter notebook (with ``output_notebook`` enabled)
-        and notebook_handle=True, returns a handle that can be used by
+        and ``notebook_handle=True``, returns a handle that can be used by
         ``push_notebook``, None otherwise.
 
     .. note::
@@ -521,9 +522,20 @@ def push(session_id=None, url=None, app_path=None, document=None, state=None, io
                     document=document, io_loop=io_loop)
 
 def push_notebook(document=None, state=None, handle=None):
-    ''' Update the last-shown plot in a Jupyter notebook with the new data
+    ''' Update Bokeh plots in a Jupyter notebook output cells with new data
     or property values.
 
+    When working the the notebook, the ``show`` function can be passed the
+    argument ``notebook_handle=True``, which will cause it to return a
+    handle object that can be used to update the Bokeh output later. When
+    ``push_notebook`` is called, any property updates (e.g. plot titles or
+    data source values, etc.) since the last call to ``push_notebook`` or
+    the original ``show`` call are applied to the Bokeh output in the
+    previously rendered Jupyter output cell.
+
+    Several example notebooks can be found in the GitHub repository in
+    the :bokeh-tree:`examples/howto/notebook_comms` directory.
+
     Args:
 
         document (Document, optional) :
@@ -542,23 +554,26 @@ def push_notebook(document=None, state=None, handle=None):
 
         .. code-block:: python
 
-            from bokeh.io import push_notebook
+            from bokeh.plotting import figure
+            from bokeh.io import output_notebook, push_notebook, show
 
-            # code to create a plot
+            output_notebook()
 
-            show(plot)
+            plot = figure()
+            plot.circle([1,2,3], [4,6,5])
 
-            plot.title = "New Title"
+            handle = show(plot, notebook_handle=True)
 
-            # This will cause the title to update
-            push_notebook()
+            # Update the plot title in the earlier cell
+            plot.title = "New Title"
+            push_notebook(handle)
 
     '''
     if state is None:
         state = _state
 
     if state.server_enabled:
-        raise RuntimeError("output_server() has been called, use push() to push to server")
+        raise RuntimeError("output_server() has been called, which is incompatible with push_notebook")
 
     if not document:
         document = state.document
@@ -571,7 +586,7 @@ def push_notebook(document=None, state=None, handle=None):
         handle = state.last_comms_handle
 
     if not handle:
-        warnings.warn("Cannot find a last shown plot to update. Call output_notebook() and show() before push_notebook()")
+        warnings.warn("Cannot find a last shown plot to update. Call output_notebook() and show(..., notebook_handle=True) before push_notebook()")
         return
 
     to_json = document.to_json()


Test patch: