DOC: Add Dataset.drop_dims() documentation

doc/api.rst

@@ -87,6 +87,7 @@ Dataset contents
    Dataset.swap_dims
    Dataset.expand_dims
    Dataset.drop
+   Dataset.drop_dims
    Dataset.set_coords
    Dataset.reset_coords
 

doc/data-structures.rst

@@ -408,6 +408,13 @@ operations keep around coordinates:
     list(ds[['x']])
     list(ds.drop('temperature'))
 
+To remove a dimension, you can use :py:meth:`~xarray.Dataset.drop_dims` method.
+Any variables using that dimension are dropped:
+
+.. ipython:: python
+
+    ds.drop_dims('time')
+
 As an alternate to dictionary-like modifications, you can use
 :py:meth:`~xarray.Dataset.assign` and :py:meth:`~xarray.Dataset.assign_coords`.
 These methods return a new dataset with additional (or replaced) or values:

doc/indexing.rst

@@ -229,7 +229,7 @@ arrays). However, you can do normal indexing with dimension names:
 Using indexing to *assign* values to a subset of dataset (e.g.,
 ``ds[dict(space=0)] = 1``) is not yet supported.
 
-Dropping labels
+Dropping labels and dimensions
 ---------------
 
 The :py:meth:`~xarray.Dataset.drop` method returns a new object with the listed
@@ -241,6 +241,15 @@ index labels along a dimension dropped:
 
 ``drop`` is both a ``Dataset`` and ``DataArray`` method.
 
+Use :py:meth:`~xarray.Dataset.drop_dims` to drop a full dimension.  Any variables
+with these dimensions are also dropped:
+
+.. ipython:: python
+
+    ds.drop_dims('time')
+
+``drop_dims`` is a ``Dataset`` method.
+
 
 .. _masking with where:
 

doc/whats-new.rst

@@ -68,6 +68,8 @@ Enhancements
 - :py:meth:`pandas.Series.dropna` is now supported for a
   :py:class:`pandas.Series` indexed by a :py:class:`~xarray.CFTimeIndex`
   (:issue:`2688`). By `Spencer Clark <https://github.com/spencerkclark>`_.
+- Added :py:meth:`~xarray.Dataset.drop_dims` (:issue:`1949`).
+  By `Kevin Squire <https://github.com/kmsquire>`_.
 
 Bug fixes
 ~~~~~~~~~