Add section about hv.render to Plots and Renderers guide

examples/user_guide/Plots_and_Renderers.ipynb

@@ -50,6 +50,125 @@
     "hv.core.options.OptionTree(opts.items()[0:10], groups=['plot', 'style', 'norm'])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Saving and rendering\n",
+    "\n",
+    "The easiest entrypoint to rendering a HoloViews object either to the backend specific representation (e.g. a matplotlib figure) or directly to file are the ``hv.render`` and ``hv.save`` functions. Both are shortcuts for using an actual ``Renderer`` object, which will be introduced in the next section. To start with we will create a simple object, a ``Scatter`` element:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "curve = hv.Curve(range(10))\n",
+    "curve"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This abstract and declarative representation of a ``Curve`` can be turned into an actual plot object, defaulting to the currently selected (or default) backend:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig = hv.render(curve)\n",
+    "print(type(fig))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "By providing an explicit ``backend`` keyword the plot can be rendered using a different backend."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = hv.render(curve, backend='bokeh')\n",
+    "print(type(p))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This can often be useful to customize a plot in more detail by tweaking styling in ways that are not directly supported by HoloViews. An alternative to ``hv.render`` in case you do not want to fully switch to the underlying plotting API are ``finalize_hooks``, which are a plot option on all elements. These allow defining hooks which modify a plot while it is being rendered.\n",
+    "\n",
+    "A ``finalize_hook`` is given the HoloViews plot instance and the currently rendered element and thereby provides access to the rendered plot object to apply any customizations and changes which are not exposed by HoloViews:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def hook(plot, element):\n",
+    "    # Allows accessing the backends figure object\n",
+    "    plot.state\n",
+    "    \n",
+    "    # The handles contain common plot objects\n",
+    "    plot.handles\n",
+    "\n",
+    "curve = curve.options(finalize_hooks=[hook])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This allows for extensive tweaking of objects before they are rendered without entirely abandoning HoloViews' API and rendering the backend's plot object manually.\n",
+    "\n",
+    "In much the same way the ``hv.save`` function allows exporting plots straight to file, by default inferring the format from the file extension:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hv.save(curve, 'curve.png')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Just like ``hv.render`` the ``hv.save`` function also allows specifying an explicit backend."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hv.save(curve, 'curve.html', backend='bokeh')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Additionally for ambiguous file extensions such as HTML it may be necessary to specify an explicit fmt to override the default, e.g. in the case of 'html' output the widgets will default to ``fmt='widgets'``, which may be changed to scrubber widgets using ``fmt='scrubber'``."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},