Merge 8bc9340 into 52548a6

.appveyor.yml

@@ -1,6 +1,6 @@
 environment:
   global:
-    CHANS_DEV: "-c pyviz/label/dev -c conda-forge"
+    CHANS_DEV: "-c pyviz/label/dev -c conda-forge -c bokeh/label/dev"
   matrix:
     - PY: "2.7"
       CONDA: "C:\\Miniconda-x64"

.travis.yml

@@ -25,7 +25,7 @@ env:
   global:
     - PYENV_VERSION=3.6
     - PKG_TEST_PYTHON="--test-python=py36 --test-python=py27"
-    - CHANS_DEV="-c pyviz/label/dev -c conda-forge"
+    - CHANS_DEV="-c pyviz/label/dev -c bokeh/label/dev -c conda-forge"
     - CHANS="-c pyviz"
     - MPLBACKEND="Agg"
 
@@ -146,7 +146,7 @@ jobs:
     - &doc_build
       <<: *default
       stage: docs_dev
-      env: DESC="docs" CHANS_DEV="-c pyviz/label/dev" HV_DOC_HTML='true' HV_DOC_GALLERY='false' HV_REQUIREMENTS="doc"
+      env: DESC="docs" CHANS_DEV="-c pyviz/label/dev -c bokeh/label/dev" HV_DOC_HTML='true' HV_DOC_GALLERY='false' HV_REQUIREMENTS="doc"
       script:
         - bokeh sampledata
         - nbsite generate-rst --org pyviz --project-name holoviews --skip ^reference
@@ -158,7 +158,7 @@ jobs:
     - &gallery_build
       <<: *doc_build
       stage: gallery_dev
-      env: DESC="gallery" CHANS_DEV="-c pyviz/label/dev" HV_DOC_HTML='true' HV_REQUIREMENTS="doc" BUCKET="dev."
+      env: DESC="gallery" CHANS_DEV="-c pyviz/label/dev -c bokeh/label/dev" HV_DOC_HTML='true' HV_REQUIREMENTS="doc" BUCKET="dev."
       script:
         - bokeh sampledata
         - pip install awscli
@@ -175,7 +175,7 @@ jobs:
 
     - <<: *gallery_build
       stage: gallery_daily
-      env: DESC="gallery" CHANS_DEV="-c pyviz/label/dev" HV_DOC_HTML='true' HV_DOC_GALLERY='true' HV_REQUIREMENTS="doc" BUCKET="build."
+      env: DESC="gallery" CHANS_DEV="-c pyviz/label/dev -c bokeh/label/dev" HV_DOC_HTML='true' HV_DOC_GALLERY='true' HV_REQUIREMENTS="doc" BUCKET="build."
 
     - <<: *doc_build
       stage: docs

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,97 @@
    "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 ratio between the units on the x-scale and the y-scale"
+   ]
+  },
+  {
+   "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=300).relabel('data_aspect=2')).cols(2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Responsive\n",
+    "\n",
+    "Since bokeh plots are rendered within a browser window which can be resized dynamically it supports responsive sizing modes allowing the plot to rescale when the window it is placed in is changed. If enabled, the behavior of ``responsive`` modes depends on whether an aspect or width/height option is set. Specifically responsive mode will only work if at least one dimension of the plot is left undefined, e.g. when width and height or width and aspect are set the plot is set to a fixed size, ignoring any ``responsive`` option. This leaves four different ``responsive`` modes:\n",
+    "\n",
+    "* **``scale_both``**: If neither a width or a height are defined but a fixed aspect is defined both axes will be scaled up to the maximum size of the container. Scaling ensures that the aspect ratio of the plot is maintained.\n",
+    "* **``stretch_both``**: If neither a width, height or aspect are defined the plot will stretch to fill all available space.\n",
+    "* **``stretch_width``**: If a height but neither a width or aspect are defined the plot will stretch to fill all available horizontal space.\n",
+    "* **``stretch_height``**: If a width but neither a height or aspect are defined the plot will stretch to fill all available vertical space.\n",
+    "\n",
+    "**Note**: In the notebook stretching and scaling the height does not increase the size of a cell.\n",
+    "\n",
+    "As a simple example let us declare a plot that has a fixed height but stretches to fit all available horizontal space:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hv.Points(data).opts(height=200, responsive=True, title='stretch width')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Similarly if we declare a fixed ``aspect`` or ``data_aspect`` responsive modes will try to fill all available space but avoid distorting the specified aspect:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "img.opts(data_aspect=10, responsive=True, title='scale both')"
    ]
   },
   {