Repository: dask/dask

Issue:
Add API docs for Resampler class
This may be a discoverability issue but I could not find API docs for the Resample class at https://docs.dask.org/en/latest/dataframe-api.html or https://docs.dask.org/en/latest/api.html

![Screenshot from 2019-10-31 18-03-15](https://user-images.githubusercontent.com/1796208/67992897-8bfe0b80-fc0c-11e9-8def-76838757601a.png)


---

Separately, but relatedly, I find the information architecture around the API docs a little confusing. Typically, when I click on the API part of docs, I expect to go to an arguably less user-friendly part of a docs website and just be able to click around all classes and methods that are available. In the dask docs, when I click on the API link in the left menu, I get taken to a curated page. If I then click on a sub area (e.g. DataFrame) I am put back into the context of user documentation.

Some examples of docs where I have developed the expectation for this pattern:
* bokeh user guide vs reference (https://docs.bokeh.org/en/latest/docs/reference.html)
* jinja2 - https://jinja.palletsprojects.com/en/2.10.x/api/
* pandas - api reference https://pandas.pydata.org/pandas-docs/stable/reference/index.html
* spark - https://spark.apache.org/docs/latest/api/python/index.html (vs programming guides https://spark.apache.org/docs/latest/sql-getting-started.html)

Conversely, djangoproject is an example of one of, in my opinion, the best documented projects out there that doesn't meet this pattern. Also sphinx. This is just to emphasize that I'm not trying to claim that there are no standards and this separate observation is just that. 





Discussion:

Resolving patch:
diff --git a/dask/dataframe/tseries/resample.py b/dask/dataframe/tseries/resample.py
--- a/dask/dataframe/tseries/resample.py
+++ b/dask/dataframe/tseries/resample.py
@@ -79,6 +79,25 @@ def _resample_bin_and_out_divs(divisions, rule, closed="left", label="left"):
 
 
 class Resampler(object):
+    """ Class for resampling timeseries data.
+
+    This class is commonly encountered when using ``obj.resample(...)`` which
+    return ``Resampler`` objects.
+
+    Parameters
+    ----------
+    obj : Dask DataFrame or Series
+        Data to be resampled.
+    rule : str, tuple, datetime.timedelta, DateOffset or None
+        The offset string or object representing the target conversion.
+    kwargs : optional
+        Keyword arguments passed to underlying pandas resampling function.
+
+    Returns
+    -------
+    Resampler instance of the appropriate type
+    """
+
     def __init__(self, obj, rule, **kwargs):
         if not obj.known_divisions:
             msg = (
@@ -101,6 +120,24 @@ def __init__(self, obj, rule, **kwargs):
         self._kwargs = kwargs
 
     def _agg(self, how, meta=None, fill_value=np.nan, how_args=(), how_kwargs={}):
+        """ Aggregate using one or more operations
+
+        Parameters
+        ----------
+        how : str
+            Name of aggregation operation
+        fill_value : scalar, optional
+            Value to use for missing values, applied during upsampling.
+            Default is NaN.
+        how_args : optional
+            Positional arguments for aggregation operation.
+        how_kwargs : optional
+            Keyword arguments for aggregation operation.
+
+        Returns
+        -------
+        Dask DataFrame or Series
+        """
         rule = self._rule
         kwargs = self._kwargs
         name = "resample-" + tokenize(


Test patch: