Repository: bokeh/bokeh

Issue:
Need methods to clear docs
After "doc merge fix" behavior is changed. Now server docs accumulate every time a server script is run, contrary to old behavior and docs (clearing on `output_server`). Should add `Document.clear` as well as `clear=True` keyword argument to `output_server`.



Discussion:
Is this really "doc merge fix" related? `output_*` didn't clear the state for quite a long time already. There was a complaint related to this on the ML recently.

That was about file examples IIRC and was solve with `reset_output` I don't recall seeing this behaviour on server examples but I could be mistaken. 


Resolving patch:
diff --git a/bokeh/document.py b/bokeh/document.py
--- a/bokeh/document.py
+++ b/bokeh/document.py
@@ -93,6 +93,18 @@ def ref(self):
 
     # "current plot" related functions
 
+    def clear(self):
+        """ Remove all plots from this `Document`
+
+        Returns:
+            None
+
+        """
+        self.context.children = []
+        context = self.context
+        self._models = {}
+        self._add(context)
+
     def hold(self, value=True):
         """ Set the hold value for this Document.
 
diff --git a/bokeh/plotting.py b/bokeh/plotting.py
--- a/bokeh/plotting.py
+++ b/bokeh/plotting.py
@@ -389,10 +389,10 @@ def figure(**kwargs):
     '''
     fig = Figure(**kwargs)
     curdoc()._current_plot = fig
-    curdoc().context.children.append(fig)
+    curdoc().add(fig)
     return fig
 
-def output_server(docname, session=None, url="default", name=None):
+def output_server(docname, session=None, url="default", name=None, clear=True):
     """ Cause plotting commands to automatically persist plots to a Bokeh server.
 
     Can use explicitly provided Session for persistence, or the default
@@ -407,6 +407,9 @@ def output_server(docname, session=None, url="default", name=None):
             if url is "default" use session.DEFAULT_SERVER_URL
         name (str, optional) :
             if name is None, use the server URL as the name
+        clear (bool, optional) :
+            should an existing server document be cleared of any existing
+            plots. (default: True)
 
     Additional keyword arguments like **username**, **userapikey**,
     and **base_url** can also be supplied.
@@ -417,7 +420,8 @@ def output_server(docname, session=None, url="default", name=None):
     .. note:: Generally, this should be called at the beginning of an
               interactive session or the top of a script.
 
-    .. note:: Calling this function will replaces any existing default Server session
+    .. note:: By default, calling this function will replaces any existing
+              default Server session.
 
     """
     global _default_session
@@ -431,6 +435,8 @@ def output_server(docname, session=None, url="default", name=None):
         session = _default_session
     session.use_doc(docname)
     session.load_document(curdoc())
+    if clear:
+        curdoc().clear()
 
 def output_notebook(url=None, docname=None, session=None, name=None,
                     force=False):
diff --git a/bokeh/session.py b/bokeh/session.py
--- a/bokeh/session.py
+++ b/bokeh/session.py
@@ -598,6 +598,7 @@ def store_document(self, doc, dirty_only=True):
             models : list[PlotObject]
 
         """
+        doc._add_all()
         models = doc._models.values()
 
         if dirty_only:


Test patch: