DOC: improve documentation for Series.resample

[cancan101]

Reference docs (see: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.Series.resample.html):

• Add to docs the list of options that can be passed to fill_method. Some of which are pad, bfill, ffill.
  -- The list seems to be documented for the method on fillna: http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.fillna.html#pandas.DataFrame.fillna
• The convention parameter is not well documented. It is unclear what the values of end or start means (and the associated aliases). (Resample convention='start' not functioning properly #15432 is dupe), PR DOC: document convention argument for resample() #16965
• The kind parameters is also unclear. The best I could get from it was a infinite stack recursion: Series.resample leads to RuntimeError: maximum recursion depth exceeded while calling a Python object #5026. (DOC: Add information on kind parameter to resample docstring #19084)
• how can also be a function or list of functions, not only a string
• for the closed and label keywords, I think it could be explained which are default in which cases (which is not always the same). In every case, that label='right' is default as stated in the docs (http://pandas.pydata.org/pandas-docs/dev/timeseries.html#up-and-downsampling) is not true.
• A list of all available methods for how

Tutorial docs:

• example using custom how function
• example showing how to use base

[jreback]

@cancan101 this one

[jorisvandenbossche]

some more issues:

1. how can also be a function or list of functions, not only a string
2. for the closed and label keywords, I think it could be explained which are default in which cases (which is not always the same). In every case, that label='right' is default as stated in the docs (http://pandas.pydata.org/pandas-docs/dev/timeseries.html#up-and-downsampling) is not true.

[Winterflower]

Working on adding examples into the resample API docs. Hopefully this will help users who don't have time to read the tutorials to use resample.

[kdebrab]

FWIW: By default resample uses start timestamp convention (i.e. closed='left' and label='left'), except for weekly, monthly, quarter and annual resolution, where the default is end timestamp convention (i.e. closed='right' and label='right', in other words the week, month, quarter or year is represented by its last day). The code doing that is here: https://github.com/pandas-dev/pandas/blob/v0.19.2/pandas/tseries/resample.py#L983-L997.

As of 0.19.2, the incorrect documentation about label='right' is to be found in the comment of code input [245] on http://pandas-docs.github.io/pandas-docs-travis/timeseries.html#basics.

[jreback]

sure a PR would be great for this

[Peque]

Apparently there is also an undocumented limit parameter (not even mentioned in the docstring).

[jorisvandenbossche]

An explanation of the limit keyword is indeed missing, but note that this stems from the previous (deprecated) interface, so maybe not worth to add it anymore (as I think we might remove those deprecated things in the next release)

[fding253]

Working on adding documentation for the convention parameter.

[mroeschke]

Since the resample API has changed since the original issue has been posted. I think most of the original points have been addressed:

• closed default behavior is specified
• how is no longer relevant (bfill and ffill are separate methods)

We can open up individual issues for any remaining improvements documentation.