DOC: update the pandas.Series/DataFrame.interpolate docstring
State: closed

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [ ] It has been proofread on language by another sprint participant

Errors in the validation script:
- Formatting of the 'method' param is not right (not sure how to break option list properly into multiple lines)
- kwargs (to ignore)
- Formatting compaints are due to extra line for "New in version ..."
```################################################################################
################### Docstring (pandas.DataFrame.interpolate) ###################
################################################################################

Interpolate values according to different methods.

Please note that only ``method='linear'`` is supported for
DataFrames/Series with a MultiIndex.

Parameters
----------
method : {'linear', 'time', 'index', 'values', 'nearest', 'zero',
          'slinear', 'quadratic', 'cubic', 'barycentric', 'krogh',
          'polynomial', 'spline', 'piecewise_polynomial', 'pad',
          'from_derivatives', 'pchip', 'akima'}, default 'linear'
    Interpolation technique to use.

    * 'linear': Ignore the index and treat the values as equally
      spaced. This is the only method supported on MultiIndexes.
      Default.
    * 'time': Interpolation works on daily and higher resolution
      data to interpolate given length of interval.
    * 'index', 'values': use the actual numerical values of the index.
    * 'pad': Fill in NaNs using existing values.
    * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic',
      'barycentric', 'polynomial': Passed to
      ``scipy.interpolate.interp1d``. Both 'polynomial' and 'spline'
      require that you also specify an `order` (int),
      e.g. df.interpolate(method='polynomial', order=4).
      These use the actual numerical values of the index.
    * 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima':
      Wrappers around the scipy interpolation methods of
      similar names. These use the actual numerical values of the
      index. For more information on their behavior, see the
      `scipy documentation
      <http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
      and `tutorial documentation
      <http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__.
    * 'from_derivatives': Refers to
      ``scipy.intrepolate.BPoly.from_derivatives`` which
      replaces 'piecewise_polynomial' interpolation method in
      scipy 0.18.

    .. versionadded:: 0.18.1

       Added support for the 'akima' method
       Added interpolate method 'from_derivatives' which replaces
       'piecewise_polynomial' in scipy 0.18; backwards-compatible with
       scipy < 0.18

axis : {0, 1}, default 0
    Axis to interpolate along.

    * 0: Fill column-by-column.
    * 1: Fill row-by-row.
limit : int, default None
    Maximum number of consecutive NaNs to fill. Must be greater than 0.
inplace : bool, default False
    Update the data in place if possible.
limit_direction : {'forward', 'backward', 'both'}, default 'forward'
    If limit is specified, consecutive NaNs will be filled in this
    direction.
limit_area : {'inside', 'outside'}, default None
    If limit is specified, consecutive NaNs will be filled with this
    restriction.

    * None: No fill restriction (default).
    * 'inside': Only fill NaNs surrounded by valid values
      (interpolate).
    * 'outside': Only fill NaNs outside valid values (extrapolate).

    .. versionadded:: 0.21.0

downcast : optional, 'infer' or None, defaults to None
    Downcast dtypes if possible.
kwargs
    Keyword arguments to pass on to the interpolating function.

Returns
-------
Series or DataFrame
    Same-shape object interpolated at the NaN values

See Also
--------
replace : replace a value
fillna : fill missing values

Examples
--------

Filling in NaNs in a Series via linear interpolation.

>>> ser = pd.Series([0, 1, np.nan, 3])
>>> ser.interpolate()
0    0.0
1    1.0
2    2.0
3    3.0
dtype: float64

Filling in NaNs in a Series by padding, but filling at most two
consecutive NaN at a time.

>>> ser = pd.Series([np.nan, "single_one", np.nan,
...                  "fill_two_more", np.nan, np.nan, np.nan,
...                  4.71, np.nan])
>>> ser
0              NaN
1       single_one
2              NaN
3    fill_two_more
4              NaN
5              NaN
6              NaN
7             4.71
8              NaN
dtype: object
>>> ser.interpolate(method='pad', limit=2)
0              NaN
1       single_one
2       single_one
3    fill_two_more
4    fill_two_more
5    fill_two_more
6              NaN
7             4.71
8             4.71
dtype: object

Create a DataFrame with missing values.

>>> df = pd.DataFrame([[0,1,2,0,4],[1,2,3,-1,8],
...                    [2,3,4,-2,12],[3,4,5,-3,16]],
...                   columns=['a', 'b', 'c', 'd', 'e'])
>>> df
   a  b  c  d   e
0  0  1  2  0   4
1  1  2  3 -1   8
2  2  3  4 -2  12
3  3  4  5 -3  16
>>> df.loc[3,'a'] = np.nan
>>> df.loc[0,'b'] = np.nan
>>> df.loc[1,'d'] = np.nan
>>> df.loc[2,'d'] = np.nan
>>> df.loc[1,'e'] = np.nan
>>> df
     a    b  c    d     e
0  0.0  NaN  2  0.0   4.0
1  1.0  2.0  3  NaN   NaN
2  2.0  3.0  4  NaN  12.0
3  NaN  4.0  5 -3.0  16.0

Fill the DataFrame forward (that is, going down) along each column.
Note how the last entry in column `a` is interpolated differently
(because there is no entry after it to use for interpolation).
Note how the first entry in column `b` remains NA (because there
is no entry befofe it to use for interpolation).

>>> df.interpolate(method='linear', limit_direction='forward', axis=0)
     a    b  c    d     e
0  0.0  NaN  2  0.0   4.0
1  1.0  2.0  3 -1.0   8.0
2  2.0  3.0  4 -2.0  12.0
3  2.0  4.0  5 -3.0  16.0

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Errors in parameters section
                Parameter "method" description should start with capital letter
                Parameter "method" description should finish with "."
                Parameter "limit_area" description should finish with "."
                Parameter "kwargs" has no type
```

Labels:
name: Docs

Comments:
Lot's of comments but just wanted to say nice job! This is one of the tougher docstrings
I hope to finish these great suggestions some time today.
Thank you for the thorough review, @WillAyd 
I made some changes. 

I believe the errors below can be ignored, because they relate to known issues (**kwargs, .. versionadded::, etc.)
```
################################################################################
################### Docstring (pandas.DataFrame.interpolate) ###################
################################################################################

Interpolate values according to different methods.

Please note that only ``method='linear'`` is supported for
DataFrames/Series with a MultiIndex.

Parameters
----------
method : {'linear', 'time', 'index', 'values', 'nearest', 'zero',
          'slinear', 'quadratic', 'cubic', 'barycentric', 'krogh',
          'polynomial', 'spline', 'piecewise_polynomial', 'pad',
          'from_derivatives', 'pchip', 'akima'}
    Interpolation technique to use.

    * 'linear': Ignore the index and treat the values as equally
      spaced. This is the only method supported on MultiIndexes.
    * 'time': Works on daily and higher resolution
      data to interpolate given length of interval.
    * 'index', 'values': use the actual numerical values of the index.
    * 'pad': Fill in NaNs using existing values.
    * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'spline',
      'barycentric', 'polynomial': Passed to
      ``scipy.interpolate.interp1d``. Both 'polynomial' and 'spline'
      require that you also specify an `order` (int),
      e.g. df.interpolate(method='polynomial', order=4).
      These use the actual numerical values of the index.
    * 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima':
      Wrappers around the scipy interpolation methods of similar
      names. See `Notes`.
    * 'from_derivatives': Refers to
      ``scipy.interpolate.BPoly.from_derivatives`` which
      replaces 'piecewise_polynomial' interpolation method in
      scipy 0.18.

    .. versionadded:: 0.18.1

       Added support for the 'akima' method
       Added interpolate method 'from_derivatives' which replaces
       'piecewise_polynomial' in scipy 0.18; backwards-compatible with
       scipy < 0.18

axis : {0 or 'index', 1 or 'columns', None}, default None
    Axis to interpolate along.
limit : int, optional
    Maximum number of consecutive NaNs to fill. Must be greater than
    0.
inplace : bool, default False
    Update the data in place if possible.
limit_direction : {'forward', 'backward', 'both'}, default 'forward'
    If limit is specified, consecutive NaNs will be filled in this
    direction.
limit_area : {`None`, 'inside', 'outside'}
    If limit is specified, consecutive NaNs will be filled with this
    restriction.

    * None: No fill restriction (default).
    * 'inside': Only fill NaNs surrounded by valid values
      (interpolate).
    * 'outside': Only fill NaNs outside valid values (extrapolate).

    .. versionadded:: 0.21.0

downcast : optional, 'infer' or None, defaults to None
    Downcast dtypes if possible.
**kwargs
    Keyword arguments to pass on to the interpolating function.

Returns
-------
Series or DataFrame
    Same-shape object interpolated at the NaN values

See Also
--------
replace : replace a value
fillna : fill missing values
scipy.interpolate.Akima1DInterpolator : piecewise cubic polynomials
    (Akima interpolator)
scipy.interpolate.BPoly.from_derivatives : piecewise polynomial in the
    Bernstein basis
scipy.interpolate.interp1d : interpolate a 1-D function
scipy.interpolate.KroghInterpolator : interpolate polynomial (Krogh
    interpolator)
scipy.interpolate.PchipInterpolator : PCHIP 1-d monotonic cubic
    interpolation
scipy.interpolate.CubicSpline : cubic spline data interpolator

Notes
-----
If the selected `method` is one of 'krogh', 'piecewise_polynomial',
'spline', 'pchip', 'akima':
They are wrappers around the scipy interpolation methods of similar
names. These use the actual numerical values of the index.
For more information on their behavior, see the
`scipy documentation
<http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
and `tutorial documentation
<http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__.

Examples
--------

Filling in `NaN` in a :class:`~pandas.Series` via linear
interpolation.

>>> s = pd.Series([0, 1, np.nan, 3])
>>> s.interpolate()
0    0.0
1    1.0
2    2.0
3    3.0
dtype: float64

Filling in `NaN` in a Series by padding, but filling at most two
consecutive `NaN` at a time.

>>> s = pd.Series([np.nan, "single_one", np.nan,
...                  "fill_two_more", np.nan, np.nan, np.nan,
...                  4.71, np.nan])
>>> s
0              NaN
1       single_one
2              NaN
3    fill_two_more
4              NaN
5              NaN
6              NaN
7             4.71
8              NaN
dtype: object
>>> s.interpolate(method='pad', limit=2)
0              NaN
1       single_one
2       single_one
3    fill_two_more
4    fill_two_more
5    fill_two_more
6              NaN
7             4.71
8             4.71
dtype: object

Filling in `NaN` in a Series via polynomial interpolation or splines:
Both `polynomial` and `spline` methods require that you also specify
an `order` (int).

>>> s = pd.Series([0, 2, np.nan, 8])
>>> s.interpolate(method='polynomial', order=1)
0    0.0
1    2.0
2    5.0
3    8.0
dtype: float64
>>> s.interpolate(method='polynomial', order=2)
0    0.000000
1    2.000000
2    4.666667
3    8.000000
dtype: float64

Create a :class:`~pandas.DataFrame` with missing values to fill it
with diffferent methods.

>>> df = pd.DataFrame([[0,1,2,0,4],[1,2,3,-1,8],
...                    [2,3,4,-2,12],[3,4,5,-3,16]],
...                   columns=['a', 'b', 'c', 'd', 'e'])
>>> df
   a  b  c  d   e
0  0  1  2  0   4
1  1  2  3 -1   8
2  2  3  4 -2  12
3  3  4  5 -3  16
>>> df.loc[1,'a'] = np.nan
>>> df.loc[3,'a'] = np.nan
>>> df.loc[0,'b'] = np.nan
>>> df.loc[1,'d'] = np.nan
>>> df.loc[2,'d'] = np.nan
>>> df.loc[1,'e'] = np.nan
>>> df
     a    b  c    d     e
0  0.0  NaN  2  0.0   4.0
1  NaN  2.0  3  NaN   NaN
2  2.0  3.0  4  NaN  12.0
3  NaN  4.0  5 -3.0  16.0

Fill the DataFrame forward (that is, going down) along each column.
Note how the last entry in column `a` is interpolated differently
(because there is no entry after it to use for interpolation).
Note how the first entry in column `b` remains `NaN` (because there
is no entry befofe it to use for interpolation).

>>> df.interpolate(method='linear', limit_direction='forward', axis=0)
     a    b  c    d     e
0  0.0  NaN  2  0.0   4.0
1  1.0  2.0  3 -1.0   8.0
2  2.0  3.0  4 -2.0  12.0
3  2.0  4.0  5 -3.0  16.0

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Errors in parameters section
                Parameters {'kwargs'} not documented
                Unknown parameters {'**kwargs'}
                Parameter "method" description should start with capital letter
                Parameter "method" description should finish with "."
                Parameter "limit_area" description should finish with "."
                Parameter "**kwargs" has no  @type
```
Hello @math-and-data! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on August 19, 2018 at 00:25 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=h1) Report
> Merging [#20270](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/92dcf5f4cce9c7221c8556f0251ec56095cc1b2b?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20270/graphs/tree.svg?src=pr&width=650&token=eZ4WkYLtcO&height=150)](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #20270   +/-   ##
=======================================
  Coverage   92.05%   92.05%           
=======================================
  Files         169      169           
  Lines       50713    50713           
=======================================
  Hits        46683    46683           
  Misses       4030     4030
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.46% <ø> (ø)` | :arrow_up: |
| #single | `42.25% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20270/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.44% <ø> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20270/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.73% <0%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=footer). Last update [92dcf5f...3f00e93](https://codecov.io/gh/pandas-dev/pandas/pull/20270?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

- [ ] docstring validation issues below, should be known kwarg and .
```
################################################################################
################### Docstring (pandas.DataFrame.interpolate) ###################
################################################################################

Interpolate values according to different methods.

Please note that only ``method='linear'`` is supported for
DataFrames/Series with a MultiIndex.

Parameters
----------
method : {'linear', 'time', 'index', 'values', 'nearest', 'zero',
          'slinear', 'quadratic', 'cubic', 'barycentric', 'krogh',
          'polynomial', 'spline', 'piecewise_polynomial', 'pad',
          'from_derivatives', 'pchip', 'akima'}
    Interpolation technique to use.

    * 'linear': Ignore the index and treat the values as equally
      spaced. This is the only method supported on MultiIndexes.
    * 'time': Works on daily and higher resolution
      data to interpolate given length of interval.
    * 'index', 'values': use the actual numerical values of the index.
    * 'pad': Fill in NaNs using existing values.
    * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic', 'spline',
      'barycentric', 'polynomial': Passed to
      ``scipy.interpolate.interp1d``. Both 'polynomial' and 'spline'
      require that you also specify an `order` (int),
      e.g. df.interpolate(method='polynomial', order=4).
      These use the numerical values of the index.
    * 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima':
      Wrappers around the SciPy interpolation methods of similar
      names. See `Notes`.
    * 'from_derivatives': Refers to
      ``scipy.interpolate.BPoly.from_derivatives`` which
      replaces 'piecewise_polynomial' interpolation method in
      scipy 0.18.

    .. versionadded:: 0.18.1

       Added support for the 'akima' method
       Added interpolate method 'from_derivatives' which replaces
       'piecewise_polynomial' in SciPy 0.18; backwards-compatible with
       SciPy < 0.18

axis : {0 or 'index', 1 or 'columns', None}, default None
    Axis to interpolate along.
limit : int, optional
    Maximum number of consecutive NaNs to fill. Must be greater than
    0.
inplace : bool, default False
    Update the data in place if possible.
limit_direction : {'forward', 'backward', 'both'}, default 'forward'
    If limit is specified, consecutive NaNs will be filled in this
    direction.
limit_area : {`None`, 'inside', 'outside'}
    If limit is specified, consecutive NaNs will be filled with this
    restriction.

    * None: No fill restriction.
    * 'inside': Only fill NaNs surrounded by valid values
      (interpolate).
    * 'outside': Only fill NaNs outside valid values (extrapolate).

    .. versionadded:: 0.21.0

downcast : optional, 'infer' or None, defaults to None
    Downcast dtypes if possible.
**kwargs
    Keyword arguments to pass on to the interpolating function.

Returns
-------
Series or DataFrame
    Returns the same object type as the caller, interpolated at
    some or all `NaN` values

See Also
--------
replace : replace a value
fillna : fill missing values
scipy.interpolate.Akima1DInterpolator : piecewise cubic polynomials
    (Akima interpolator)
scipy.interpolate.BPoly.from_derivatives : piecewise polynomial in the
    Bernstein basis
scipy.interpolate.interp1d : interpolate a 1-D function
scipy.interpolate.KroghInterpolator : interpolate polynomial (Krogh
    interpolator)
scipy.interpolate.PchipInterpolator : PCHIP 1-d monotonic cubic
    interpolation
scipy.interpolate.CubicSpline : cubic spline data interpolator

Notes
-----
The 'krogh', 'piecewise_polynomial', 'spline', 'pchip' and 'akima'
methods are wrappers around the respective SciPy implementations of
similar names. These use the actual numerical values of the index.
For more information on their behavior, see the
`SciPy documentation
<http://docs.scipy.org/doc/scipy/reference/interpolate.html#univariate-interpolation>`__
and `SciPy tutorial
<http://docs.scipy.org/doc/scipy/reference/tutorial/interpolate.html>`__.

Examples
--------

Filling in `NaN` in a :class:`~pandas.Series` via linear
interpolation.

>>> s = pd.Series([0, 1, np.nan, 3])
>>> s.interpolate()
0    0.0
1    1.0
2    2.0
3    3.0
dtype: float64

Filling in `NaN` in a Series by padding, but filling at most two
consecutive `NaN` at a time.

>>> s = pd.Series([np.nan, "single_one", np.nan,
...                "fill_two_more", np.nan, np.nan, np.nan,
...                4.71, np.nan])
>>> s
0              NaN
1       single_one
2              NaN
3    fill_two_more
4              NaN
5              NaN
6              NaN
7             4.71
8              NaN
dtype: object
>>> s.interpolate(method='pad', limit=2)
0              NaN
1       single_one
2       single_one
3    fill_two_more
4    fill_two_more
5    fill_two_more
6              NaN
7             4.71
8             4.71
dtype: object

Filling in `NaN` in a Series via polynomial interpolation or splines:
Both `polynomial` and `spline` methods require that you also specify
an `order` (int).

>>> s = pd.Series([0, 2, np.nan, 8])
>>> s.interpolate(method='polynomial', order=2)
0    0.000000
1    2.000000
2    4.666667
3    8.000000
dtype: float64

Filling in `NaN` in a :class:`~pandas.DataFrame` via linear
interpolation.

>>> df = pd.DataFrame({'a': range(0,4),
...                    'b': range(1,5),
...                    'c': range(-1, -5, -1),
...                    'd': [x**2 for x in range(1,5)]})
>>> df
   a  b  c   d
0  0  1 -1   1
1  1  2 -2   4
2  2  3 -3   9
3  3  4 -4  16
>>> df.loc[1,'a'] = np.nan
>>> df.loc[3,'a'] = np.nan
>>> df.loc[0,'b'] = np.nan
>>> df.loc[1,'c'] = np.nan
>>> df.loc[2,'c'] = np.nan
>>> df.loc[1,'d'] = np.nan
>>> df
     a    b    c     d
0  0.0  NaN -1.0   1.0
1  NaN  2.0  NaN   NaN
2  2.0  3.0  NaN   9.0
3  NaN  4.0 -4.0  16.0

Fill the DataFrame forward (that is, going down) along each column.
Note how the last entry in column `a` is interpolated differently,
because there is no entry after it to use for interpolation.
Note how the first entry in column `b` remains `NaN`, because there
is no entry befofe it to use for interpolation.

>>> df.interpolate(method='linear', limit_direction='forward', axis=0)
     a    b    c     d
0  0.0  NaN -1.0   1.0
1  1.0  2.0 -2.0   5.0
2  2.0  3.0 -3.0   9.0
3  2.0  4.0 -4.0  16.0

>>> df['d'].interpolate(method='polynomial', order=2)
0     1.0
1     4.0
2     9.0
3    16.0
Name: d, dtype: float64

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Errors in parameters section
                Parameters {'kwargs'} not documented
                Unknown parameters {'**kwargs'}
                Parameter "method" description should start with capital letter
                Parameter "method" description should finish with "."
                Parameter "limit_area" description should finish with "."
                Parameter "**kwargs" has no type
```
Yep, agree. I think they should be all right now. Thanks @WillAyd !
Thanks @math-and-data and @datapythonista !