Add broadcast function to the API

[shoyer]

This is a renaming and update of the existing xray.broadcast_arrays function,
which now works properly in the light of #648.

xref #649
cc @rabernat

Examples

Broadcast two data arrays against one another to fill out their dimensions:

>>> a = xray.DataArray([1, 2, 3], dims='x')
>>> b = xray.DataArray([5, 6], dims='y')
>>> a
<xray.DataArray (x: 3)>
array([1, 2, 3])
Coordinates:
  * x        (x) int64 0 1 2
>>> b
<xray.DataArray (y: 2)>
array([5, 6])
Coordinates:
  * y        (y) int64 0 1
>>> a2, b2 = xray.broadcast(a, b)
>>> a2
<xray.DataArray (x: 3, y: 2)>
array([[1, 1],
       [2, 2],
       [3, 3]])
Coordinates:
  * x        (x) int64 0 1 2
  * y        (y) int64 0 1
>>> b2
<xray.DataArray (x: 3, y: 2)>
array([[5, 6],
       [5, 6],
       [5, 6]])
Coordinates:
  * y        (y) int64 0 1
  * x        (x) int64 0 1 2

Fill out the dimensions of all data variables in a dataset:

>>> ds = xray.Dataset({'a': a, 'b': b})
>>> ds2, = xray.broadcast(ds)  # use tuple unpacking to extract one dataset
>>> ds2
<xray.Dataset>
Dimensions:  (x: 3, y: 2)
Coordinates:
  * x        (x) int64 0 1 2
  * y        (y) int64 0 1
Data variables:
    a        (x, y) int64 1 1 2 2 3 3
    b        (x, y) int64 5 6 5 6 5 6

[shoyer]

Any comments? This needs a rebase, but is otherwise ready for review

[rabernat]

Can there be a test for broadcasting coordinates, not just data variables? That is something I use frequently, and I currently have to hack it (as in #649).

[shoyer]

I'll add some more explicit tests.

[shoyer]

done

[jhamman]

LGTM.

[shoyer]

thanks for the feedback, guys!