Docs and other minor updates for v0.10.2. (#1984)

* Docs and other minor udpates for v0.10.2.

* Update build deps

* Misc doc fixes

* Removal failure on warning in doc build

Author: shoyer

.travis.yml

@@ -102,8 +102,8 @@ script:
   - flake8 -j auto xarray
   - python -OO -c "import xarray"
   - if [[ "$CONDA_ENV" == "docs" ]]; then
-      conda install -c conda-forge sphinx_rtd_theme;
-      sphinx-build -n -b html -d _build/doctrees doc _build/html;
+      conda install -c conda-forge sphinx sphinx_rtd_theme sphinx-gallery numpydoc;
+      sphinx-build -n -j auto -b html -d _build/doctrees doc _build/html;
     else
       py.test xarray --cov=xarray --cov-config ci/.coveragerc --cov-report term-missing --verbose $EXTRA_FLAGS;
     fi

README.rst

@@ -14,7 +14,7 @@ xarray: N-D labeled arrays and datasets
 .. image:: https://zenodo.org/badge/13221727.svg
   :target: https://zenodo.org/badge/latestdoi/13221727
 .. image:: http://img.shields.io/badge/benchmarked%20by-asv-green.svg?style=flat
-  :target: https://tomaugspurger.github.io/asv-collection/xarray/
+  :target: http://pandas.pydata.org/speed/xarray/
 
 **xarray** (formerly **xray**) is an open source project and Python package that aims to bring the
 labeled data power of pandas_ to the physical sciences, by providing

doc/_static/ci.png

@@ -9,6 +9,9 @@
 
    auto_combine
 
+   Dataset.nbytes
+   Dataset.chunks
+
    Dataset.all
    Dataset.any
    Dataset.argmax
@@ -42,9 +45,13 @@
    Dataset.rank
 
    DataArray.ndim
+   DataArray.nbytes
    DataArray.shape
    DataArray.size
    DataArray.dtype
+   DataArray.nbytes
+   DataArray.chunks
+
    DataArray.astype
    DataArray.item
 

doc/api-hidden.rst

@@ -52,6 +52,8 @@ Attributes
    Dataset.encoding
    Dataset.indexes
    Dataset.get_index
+   Dataset.chunks
+   Dataset.nbytes
 
 Dictionary interface
 --------------------
@@ -122,6 +124,7 @@ Missing value handling
 
    Dataset.isnull
    Dataset.notnull
+   Dataset.combine_first
    Dataset.count
    Dataset.dropna
    Dataset.fillna
@@ -160,6 +163,7 @@ Computation
 :py:attr:`~Dataset.var`
 
 **ndarray methods**:
+:py:attr:`~Dataset.astype`
 :py:attr:`~Dataset.argsort`
 :py:attr:`~Dataset.clip`
 :py:attr:`~Dataset.conj`
@@ -222,6 +226,8 @@ Attributes
 :py:attr:`~DataArray.shape`
 :py:attr:`~DataArray.size`
 :py:attr:`~DataArray.dtype`
+:py:attr:`~DataArray.nbytes`
+:py:attr:`~DataArray.chunks`
 
 DataArray contents
 ------------------
@@ -270,6 +276,7 @@ Missing value handling
 
   DataArray.isnull
   DataArray.notnull
+  DataArray.combine_first
   DataArray.count
   DataArray.dropna
   DataArray.fillna
@@ -298,6 +305,7 @@ Computation
    DataArray.groupby
    DataArray.groupby_bins
    DataArray.rolling
+   DataArray.dt
    DataArray.resample
    DataArray.get_axis_num
    DataArray.diff
@@ -480,6 +488,7 @@ DataArray methods
    DataArray.from_series
    DataArray.from_cdms2
    DataArray.from_dict
+   DataArray.close
    DataArray.compute
    DataArray.persist
    DataArray.load
@@ -517,6 +526,7 @@ Plotting
 .. autosummary::
    :toctree: generated/
 
+   DataArray.plot
    plot.plot
    plot.contourf
    plot.contour
@@ -551,6 +561,8 @@ Advanced API
 .. autosummary::
    :toctree: generated/
 
+   Dataset.variables
+   DataArray.variable
    Variable
    IndexVariable
    as_variable

doc/api.rst

@@ -662,7 +662,7 @@ Information on how to write a benchmark and how to use asv can be found in the
 `asv documentation <https://asv.readthedocs.io/en/latest/writing_benchmarks.html>`_.
 
 The ``xarray`` benchmarking suite is run remotely and the results are
-available `here <http://pandas.pydata.org/speed/xarray/`_.
+available `here <http://pandas.pydata.org/speed/xarray/>`_.
 
 Documenting your code
 ---------------------

doc/contributing.rst

@@ -27,10 +27,11 @@ What's New
 
 .. _whats-new.0.10.2:
 
-v0.10.2 (unreleased)
---------------------
+v0.10.2 (12 March 2018)
+-----------------------
 
-The minor release includes a number of bug-fixes and backwards compatible enhancements.
+The minor release includes a number of bug-fixes and enhancements, along with
+one possibly **backwards incompatible change**.
 
 Backwards incompatible changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -44,9 +45,6 @@ Backwards incompatible changes
 
 .. _ufunc methods: https://docs.scipy.org/doc/numpy/reference/ufuncs.html#methods
 
-Documentation
-~~~~~~~~~~~~~
-
 Enhancements
 ~~~~~~~~~~~~
 

doc/whats-new.rst

@@ -36,22 +36,28 @@ def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
         if ufunc.signature is not None:
             raise NotImplementedError(
                 '{} not supported: xarray objects do not directly implement '
-                'generalized ufuncs. Instead, use xarray.apply_ufunc.'
+                'generalized ufuncs. Instead, use xarray.apply_ufunc or '
+                'explicitly convert to xarray objects to NumPy arrays '
+                '(e.g., with `.values`).'
                 .format(ufunc))
 
         if method != '__call__':
             # TODO: support other methods, e.g., reduce and accumulate.
             raise NotImplementedError(
                 '{} method for ufunc {} is not implemented on xarray objects, '
-                'which currently only support the __call__ method.'
+                'which currently only support the __call__ method. As an '
+                'alternative, consider explicitly converting xarray objects '
+                'to NumPy arrays (e.g., with `.values`).'
                 .format(method, ufunc))
 
         if any(isinstance(o, SupportsArithmetic) for o in out):
             # TODO: implement this with logic like _inplace_binary_op. This
             # will be necessary to use NDArrayOperatorsMixin.
             raise NotImplementedError(
                 'xarray objects are not yet supported in the `out` argument '
-                'for ufuncs.')
+                'for ufuncs. As an alternative, consider explicitly '
+                'converting xarray objects to NumPy arrays (e.g., with '
+                '`.values`).')
 
         join = dataset_join = OPTIONS['arithmetic_join']
 

xarray/core/arithmetic.py

@@ -277,8 +277,8 @@ class Indexes(Mapping, formatting.ReprMixin):
     def __init__(self, variables, sizes):
         """Not for public consumption.
 
-        Arguments
-        ---------
+        Parameters
+        ----------
         variables : OrderedDict[Any, Variable]
             Reference to OrderedDict holding variable objects. Should be the
             same dictionary used by the source object.

xarray/core/coordinates.py

@@ -363,6 +363,7 @@ def name(self, value):
 
     @property
     def variable(self):
+        """Low level interface to the Variable object for this DataArray."""
         return self._variable
 
     @property

xarray/core/dataarray.py

@@ -399,8 +399,12 @@ def load_store(cls, store, decoder=None):
 
     @property
     def variables(self):
-        """Frozen dictionary of xarray.Variable objects constituting this
-        dataset's data
+        """Low level interface to Dataset contents as dict of Variable objects.
+
+        This ordered dictionary is frozen to prevent mutation that could
+        violate Dataset invariants. It contains all variable objects
+        constituting the Dataset, including both data variables and
+        coordinates.
         """
         return Frozen(self._variables)
 
@@ -2775,8 +2779,8 @@ def to_dask_dataframe(self, dim_order=None, set_index=False):
         The dimensions, coordinates and data variables in this dataset form
         the columns of the DataFrame.
 
-        Arguments
-        ---------
+        Parameters
+        ----------
         dim_order : list, optional
             Hierarchical dimension order for the resulting dataframe. All
             arrays are transposed to this order and then written out as flat

xarray/core/dataset.py

@@ -775,8 +775,8 @@ def _decompose_vectorized_indexer(indexer, shape, indexing_support):
     backend_indexer: OuterIndexer or BasicIndexer
     np_indexers: an ExplicitIndexer (VectorizedIndexer / BasicIndexer)
 
-    Note
-    ----
+    Notes
+    -----
     This function is used to realize the vectorized indexing for the backend
     arrays that only support basic or outer indexing.
 
@@ -846,8 +846,8 @@ def _decompose_outer_indexer(indexer, shape, indexing_support):
     backend_indexer: OuterIndexer or BasicIndexer
     np_indexers: an ExplicitIndexer (OuterIndexer / BasicIndexer)
 
-    Note
-    ----
+    Notes
+    -----
     This function is used to realize the vectorized indexing for the backend
     arrays that only support basic or outer indexing.
 

xarray/core/indexing.py

@@ -195,11 +195,8 @@ def construct(self, window_dim, stride=1, fill_value=dtypes.NA):
 
         Returns
         -------
-        DataArray that is a view of the original array.
-
-        Note
-        ----
-        The return array is not writeable.
+        DataArray that is a view of the original array. The returned array is
+        not writeable.
 
         Examples
         --------