DOC: Added examples to rolling.py (#1574)

* Added examples to doc

Added a comprehensive rolling example

* Revert back to original rolling.py

Removed my example

* DOC: added an example in def rolling()

* Revert back to latest rolling.py

* DOC: rolling.py example

Shed a few lines of my example

* Update common.py

cleaned up rolling example

* DOC: rolling.py example

Extended the description of the rolling.py example

* DOC: rolling.py example

Realized I didn't need to create a variable, as I can simply show the output

* DOC: add rolling.py example

Cleaned up the example text to add a comment in the middle

* formatting

Author: Ray Bell

xarray/core/common.py

@@ -474,6 +474,33 @@ def rolling(self, min_periods=None, center=False, **windows):
         Returns
         -------
         rolling : type of input argument
+        
+        Examples
+        --------
+        Create rolling seasonal average of monthly data e.g. DJF, JFM, ..., SON:
+        
+        >>> da = xr.DataArray(np.linspace(0,11,num=12),
+        ...                   coords=[pd.date_range('15/12/1999',
+        ...                           periods=12, freq=pd.DateOffset(months=1))], 
+        ...                   dims='time')
+        >>> da
+        <xarray.DataArray (time: 12)>
+        array([  0.,   1.,   2.,   3.,   4.,   5.,   6.,   7., 8.,   9.,  10.,  11.])
+        Coordinates:
+          * time     (time) datetime64[ns] 1999-12-15 2000-01-15 2000-02-15 ...
+        >>> da.rolling(time=3).mean()
+        <xarray.DataArray (time: 12)>
+        array([ nan,  nan,   1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.])
+        Coordinates:
+          * time     (time) datetime64[ns] 1999-12-15 2000-01-15 2000-02-15 ...
+
+        Remove the NaNs using ``dropna()``:
+        
+        >>> da.rolling(time=3).mean().dropna('time')
+        <xarray.DataArray (time: 10)>
+        array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.])
+        Coordinates:
+          * time     (time) datetime64[ns] 2000-02-15 2000-03-15 2000-04-15 ...
         """
 
         return self._rolling_cls(self, min_periods=min_periods,