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,8 +229,8 @@ 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
 index labels along a dimension dropped:
@@ -241,6 +241,13 @@ 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 from a Dataset.
+Any variables with these dimensions are also dropped:
+
+.. ipython:: python
+
+    ds.drop_dims('time')
+
 
 .. _masking with where:
 

doc/whats-new.rst

@@ -78,6 +78,9 @@ Enhancements
   serialization warnings raised if dates from a standard calendar are found to
   be outside the :py:class:`pandas.Timestamp`-valid range (:issue:`2754`).  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
 ~~~~~~~~~