Repository: pandas-dev/pandas

Issue:
DOC: warnings from doc-strings for deprecated functions
various warnings we should fix by fixing the doc-strings (e.g. for clip_upper change to using clip in the examples

```
Validate docstrings (GL06, GL07, GL09, SS04, PR03, PR05, EX04)
ci/../scripts/validate_docstrings.py:764: PerformanceWarning: indexing past lexsort depth may impact performance.
  errs, wrns, examples_errs = get_validation_data(doc)
ci/../scripts/validate_docstrings.py:1: FutureWarning: clip_lower(threshold) is deprecated, use clip(lower=threshold) instead
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:1: FutureWarning: clip_upper(threshold) is deprecated, use clip(upper=threshold) instead
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:2: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  """
ci/../scripts/validate_docstrings.py:2: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  """
ci/../scripts/validate_docstrings.py:1: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:1: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:1: FutureWarning: clip_lower(threshold) is deprecated, use clip(lower=threshold) instead
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:1: FutureWarning: clip_upper(threshold) is deprecated, use clip(upper=threshold) instead
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:2: FutureWarning: '.reindex_axis' is deprecated and will be removed in a future version. Use '.reindex' instead.
  """
ci/../scripts/validate_docstrings.py:524: DtypeWarning: Columns (0) have mixed types. Specify dtype option on import or set low_memory=False.
  runner.run(test, out=f.write)
ci/../scripts/validate_docstrings.py:2: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  """
ci/../scripts/validate_docstrings.py:2: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  """
ci/../scripts/validate_docstrings.py:1: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
  #!/usr/bin/env python
ci/../scripts/validate_docstrings.py:1: FutureWarning: Creating a DatetimeIndex by passing range endpoints is deprecated.  Use `pandas.date_range` instead.
```


Discussion:
cc @datapythonista 
All those are recent. I think besides fixing them we also need to change the validation script to add which is the docstring causing the warning, and to exit the script with return code != 0 when warnings are found.

Will create a separate issue.

Resolving patch:
diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py
--- a/pandas/core/arrays/datetimes.py
+++ b/pandas/core/arrays/datetimes.py
@@ -766,8 +766,8 @@ def tz_convert(self, tz):
         With the `tz` parameter, we can change the DatetimeIndex
         to other time zones:
 
-        >>> dti = pd.DatetimeIndex(start='2014-08-01 09:00',
-        ...                        freq='H', periods=3, tz='Europe/Berlin')
+        >>> dti = pd.date_range(start='2014-08-01 09:00',
+        ...                     freq='H', periods=3, tz='Europe/Berlin')
 
         >>> dti
         DatetimeIndex(['2014-08-01 09:00:00+02:00',
@@ -784,8 +784,8 @@ def tz_convert(self, tz):
         With the ``tz=None``, we can remove the timezone (after converting
         to UTC if necessary):
 
-        >>> dti = pd.DatetimeIndex(start='2014-08-01 09:00',freq='H',
-        ...                        periods=3, tz='Europe/Berlin')
+        >>> dti = pd.date_range(start='2014-08-01 09:00',freq='H',
+        ...                     periods=3, tz='Europe/Berlin')
 
         >>> dti
         DatetimeIndex(['2014-08-01 09:00:00+02:00',
@@ -1037,8 +1037,8 @@ def normalize(self):
 
         Examples
         --------
-        >>> idx = pd.DatetimeIndex(start='2014-08-01 10:00', freq='H',
-        ...                        periods=3, tz='Asia/Calcutta')
+        >>> idx = pd.date_range(start='2014-08-01 10:00', freq='H',
+        ...                     periods=3, tz='Asia/Calcutta')
         >>> idx
         DatetimeIndex(['2014-08-01 10:00:00+05:30',
                        '2014-08-01 11:00:00+05:30',
@@ -1164,7 +1164,7 @@ def month_name(self, locale=None):
 
         Examples
         --------
-        >>> idx = pd.DatetimeIndex(start='2018-01', freq='M', periods=3)
+        >>> idx = pd.date_range(start='2018-01', freq='M', periods=3)
         >>> idx
         DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31'],
                       dtype='datetime64[ns]', freq='M')
@@ -1200,7 +1200,7 @@ def day_name(self, locale=None):
 
         Examples
         --------
-        >>> idx = pd.DatetimeIndex(start='2018-01-01', freq='D', periods=3)
+        >>> idx = pd.date_range(start='2018-01-01', freq='D', periods=3)
         >>> idx
         DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03'],
                       dtype='datetime64[ns]', freq='D')
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -4433,8 +4433,8 @@ def _reindex_multi(self, axes, copy, fill_value):
               num_legs  num_wings
         dog          4          0
         hawk         2          2
-        >>> df.reindex_axis(['num_wings', 'num_legs', 'num_heads'],
-        ...                 axis='columns')
+        >>> df.reindex(['num_wings', 'num_legs', 'num_heads'],
+        ...            axis='columns')
               num_wings  num_legs  num_heads
         dog           0         4        NaN
         hawk          2         2        NaN
@@ -7352,7 +7352,7 @@ def clip_upper(self, threshold, axis=None, inplace=False):
         4    5
         dtype: int64
 
-        >>> s.clip_upper(3)
+        >>> s.clip(upper=3)
         0    1
         1    2
         2    3
@@ -7360,11 +7360,11 @@ def clip_upper(self, threshold, axis=None, inplace=False):
         4    3
         dtype: int64
 
-        >>> t = [5, 4, 3, 2, 1]
-        >>> t
+        >>> elemwise_thresholds = [5, 4, 3, 2, 1]
+        >>> elemwise_thresholds
         [5, 4, 3, 2, 1]
 
-        >>> s.clip_upper(t)
+        >>> s.clip(upper=elemwise_thresholds)
         0    1
         1    2
         2    3
@@ -7428,7 +7428,7 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         Series single threshold clipping:
 
         >>> s = pd.Series([5, 6, 7, 8, 9])
-        >>> s.clip_lower(8)
+        >>> s.clip(lower=8)
         0    8
         1    8
         2    8
@@ -7440,7 +7440,7 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         should be the same length as the Series.
 
         >>> elemwise_thresholds = [4, 8, 7, 2, 5]
-        >>> s.clip_lower(elemwise_thresholds)
+        >>> s.clip(lower=elemwise_thresholds)
         0    5
         1    8
         2    7
@@ -7457,7 +7457,7 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         1  3  4
         2  5  6
 
-        >>> df.clip_lower(3)
+        >>> df.clip(lower=3)
            A  B
         0  3  3
         1  3  4
@@ -7466,7 +7466,7 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         Or to an array of values. By default, `threshold` should be the same
         shape as the DataFrame.
 
-        >>> df.clip_lower(np.array([[3, 4], [2, 2], [6, 2]]))
+        >>> df.clip(lower=np.array([[3, 4], [2, 2], [6, 2]]))
            A  B
         0  3  4
         1  3  4
@@ -7476,13 +7476,13 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         `threshold` should be the same length as the axis specified by
         `axis`.
 
-        >>> df.clip_lower([3, 3, 5], axis='index')
+        >>> df.clip(lower=[3, 3, 5], axis='index')
            A  B
         0  3  3
         1  3  4
         2  5  6
 
-        >>> df.clip_lower([4, 5], axis='columns')
+        >>> df.clip(lower=[4, 5], axis='columns')
            A  B
         0  4  5
         1  4  5


Test patch: