Added docs for bokeh plot sizing

examples/user_guide/Plotting_with_Bokeh.ipynb

@@ -153,14 +153,34 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Sizing Elements"
+    "## Sizing Elements\n",
+    "\n",
+    "In the bokeh backend the sizing of plots and specifically layouts of plots is determined in an inside-out or compositional manner. Each subplot can be sized independently and it will fill the allocated space. The sizing is determined by the combination of width, height, aspect and responsive options. In this section we will discover the different approaches to setting plot dimensions and aspects. \n",
+    "\n",
+    "### Width and height\n",
+    "\n",
+    "The most straightforward approach to specifying the size of a plot is using a width and height specified in pixels. This is the default behavior and makes it easy to achieve precise alignment between plots but does not allow for keeping a constant aspect or responsive resizing. In particular, the specified size includes the axes and any legends or colorbars."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "points_a = hv.Points(data)\n",
+    "points_b = hv.Points(data)\n",
+    "\n",
+    "points_a.opts(width=300, height=300) + points_b.opts(width=600, height=300)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Sizing and aspect of Elements in bokeh are always computed in absolute pixels. To change the size or aspect of an Element set the ``width`` and ``height`` plot options."
+    "### Frame width and height\n",
+    "\n",
+    "The frame width on the other hand provides precise control over the inner dimensions of a plot, it ensures the actual plot frame matches the specified dimensions exactly. This makes it possible to achieve a precise aspect ratio between the axis scales, without worrying about the size of axes, colorbars, titles and legends, e.g. below we can see two plots defined using explicit ``frame_width`` and ``frame_height`` share the same dimensions despite the fact that one has a colorbar."
    ]
   },
   {
@@ -169,10 +189,54 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "points_a = hv.Points(data, label='A')\n",
-    "points_b = hv.Points(data, label='B')\n",
+    "xs = ys  = np.arange(10)\n",
+    "yy, xx = np.meshgrid(xs, ys)\n",
+    "zz = xx*yy\n",
     "\n",
-    "points_a.opts(width=300, height=300) + points_b.opts(width=600, height=300)"
+    "img = hv.Image(np.random.rand(100, 100))\n",
+    "\n",
+    "points_a.opts(frame_width=200, frame_height=200) +\\\n",
+    "img.opts(frame_width=200, frame_height=200, colorbar=True, axiswise=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Aspect\n",
+    "\n",
+    "The ``aspect`` and ``data_aspect`` options provide control over the scaling of the plot dimensions and the axis limits.\n",
+    "\n",
+    "#### ``aspect``:\n",
+    "\n",
+    "The ``aspect`` specifies the ratio between the width and height dimensions of the plot. If specified this options takes absolute precedence over the dimensions of the plot but has no effect on the plot's axis limits. It supports the following options:\n",
+    "\n",
+    "* **``float``** : A numeric value will scale the ratio of plot width to plot height\n",
+    "* **``\"equal\"``** : Sets aspect of the axis scaling to be equal, equivalent to **``data_aspect=1``**\n",
+    "* **``\"square\"``** : Ensures the plot dimensions are square.\n",
+    "\n",
+    "#### ``data_aspect``:\n",
+    "\n",
+    "The ``data_aspect`` specifies the scaling between the x- and y-axis ranges. If specified this option will scale both the plot ranges and dimensions unless explicit ``aspect``, ``width`` or ``height`` value overrides the plot dimensions:\n",
+    "\n",
+    "* **``float``** : Sets aspect of the axis scaling to be equal"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xs = np.linspace(0, 10)\n",
+    "ys = np.linspace(0, 5)\n",
+    "\n",
+    "img = hv.Image((xs, ys, xs[:, np.newaxis]*np.sin(ys*4)))\n",
+    "\n",
+    "(img.options(aspect='equal').relabel('aspect=\\'equal\\'') +\n",
+    " img.options(aspect='square', colorbar=True, width=300).relabel('aspect=\\'square\\'') +\n",
+    " img.options(aspect=2).relabel('aspect=2') + \n",
+    " img.options(data_aspect=2, width=150).relabel('data_aspect=2')).cols(2)"
    ]
   },
   {