Repository: pandas-dev/pandas
Pull request: DOC: Update Sphinx Deprecated Directive
 - [x] closes #16507 
 - [x] tests added / passed
 - [x] passes ``git diff upstream/master --name-only -- '*.py' | flake8 --diff``
 - [x] whatsnew entry

XR #6581 for version numbers. Hopefully whitespace is okay.

Problem statement:
DOC: Update docs to use sphinx deprecated directive
As an example:

```
sheetname : string, int, mixed list of strings/ints, or None, default 0
    .. deprecated:: 0.21.0
       Use `sheet_name` instead

```

Some examples that need to be replaced (line numbers, and maybe filenames will change)

```
doc/source/io.rst:140:  DEPRECATED: this argument will be removed in a future version. Please call
doc/source/io.rst:194:  DEPRECATED: use the ``skipfooter`` parameter instead, as they are identical
doc/source/io.rst:205:    DEPRECATED: this argument will be removed in a future version because its
doc/source/io.rst:208:  DEPRECATED: this argument will be removed in a future version
doc/source/io.rst:214:  DEPRECATED: this argument will be removed in a future version
doc/sphinxext/numpydoc/README.rst:49:- numpydoc_edit_link: bool  (DEPRECATED -- edit your HTML template instead)
pandas/_libs/tslib.pyx:1151:        DEPRECATED: use :meth:`to_pydatetime` instead.
pandas/core/common.py:551:    DEPRECATED: This is no longer needed, or working, in IPython 3 and above.
pandas/core/common.py:569:    DEPRECATED: This is no longer used in pandas, and won't work in IPython 3
pandas/core/categorical.py:394:        DEPRECATED: calling this method will raise an error in a
pandas/core/categorical.py:426:        DEPRECATED: Use ``Categorical`` instead.
pandas/core/categorical.py:1445:        DEPRECATED: use :meth:`Categorical.sort_values`. That function
pandas/core/categorical.py:1459:        DEPRECATED: use :meth:`Categorical.sort_values`. That function
pandas/core/dtypes/common.py:691:    DEPRECATED: This function will be removed in a future version.
pandas/core/dtypes/common.py:1490:    DEPRECATED: This function will be removed in a future version.
pandas/core/frame.py:3480:        DEPRECATED: use :meth:`DataFrame.sort_index`
pandas/core/generic.py:1325:            DEPRECATED: this parameter will be removed in a future version,
pandas/core/generic.py:3074:        DEPRECATED: consolidate will be an internal implementation only.
pandas/core/generic.py:3285:        raise_on_error : DEPRECATED use ``errors`` instead
pandas/core/generic.py:5544:        infer_dst : boolean, default False (DEPRECATED)
pandas/core/indexes/base.py:1011:        DEPRECATED: use :meth:`pandas.to_datetime` instead.
pandas/core/indexes/period.py:569:        DEPRECATED: use :meth:`to_timestamp` instead.
pandas/core/indexes/datetimes.py:200:    infer_dst : boolean, default False (DEPRECATED)
pandas/core/indexes/datetimes.py:1821:        infer_dst : boolean, default False (DEPRECATED)
pandas/core/panel4d.py:22:    DEPRECATED. Panel4D is deprecated and will be removed in a future version.
pandas/core/panelnd.py:12:    DEPRECATED. Panelnd is deprecated and will be removed in a future version.
pandas/core/series.py:853:        DEPRECATED: calling this method will raise an error in a
pandas/core/series.py:1943:        DEPRECATED: use :meth:`Series.sort_index`
pandas/core/sparse/array.py:394:            DEPRECATED: this argument will be removed in a future version
pandas/core/sparse/series.py:538:            DEPRECATED: this argument will be removed in a future version.
pandas/core/strings.py:481:    as_indexer : DEPRECATED
pandas/core/window.py:344:    how : string, default None (DEPRECATED)
pandas/core/window.py:352:    how : string, default None (DEPRECATED)
pandas/core/window.py:376:    freq : string or DateOffset object, optional (default None) (DEPRECATED)
pandas/core/window.py:573:        how : string, default to None (DEPRECATED)
pandas/core/window.py:738:        how : string, default to None (DEPRECATED)
pandas/core/window.py:866:    how : string, default 'max' (DEPRECATED)
pandas/core/window.py:880:    how : string, default 'min' (DEPRECATED)
pandas/core/window.py:898:    how : string, default 'median' (DEPRECATED)
pandas/core/window.py:1325:    freq : string or DateOffset object, optional (default None) (DEPRECATED)
pandas/core/window.py:1589:    freq : None or string alias / date offset object, default=None (DEPRECATED)
pandas/core/window.py:1723:        how : string, default to None (DEPRECATED)
pandas/io/excel.py:145:    DEPRECATED: for version 0.17+ index names will be automatically
pandas/io/parsers.py:108:    DEPRECATED: this argument will be removed in a future version. Please call
pandas/io/parsers.py:148:    DEPRECATED: use the `skipfooter` parameter instead, as they are identical
pandas/io/parsers.py:279:    DEPRECATED: this argument will be removed in a future version because its
pandas/io/parsers.py:282:    DEPRECATED: this argument will be removed in a future version
pandas/io/parsers.py:289:    DEPRECATED: this argument will be removed in a future version
pandas/io/sql.py:435:        DEPRECATED: this parameter will be removed in a future version
pandas/io/sql.py:487:        DEPRECATED: this parameter will be removed in a future version
pandas/io/sql.py:1548:        DEPRECATED: this parameter will be removed in a future version
pandas/io/stata.py:1410:    @Appender('DEPRECATED: ' + _data_method_doc)
```

Hints from issue discussion:

Commit message: Removed references to future versions

Patch to review:
diff --git a/doc/source/io.rst b/doc/source/io.rst
index bca23dd18a0e3..52d57e1d1f49b 100644
--- a/doc/source/io.rst
+++ b/doc/source/io.rst
@@ -137,8 +137,8 @@ usecols : array-like or callable, default ``None``
 
   Using this parameter results in much faster parsing time and lower memory usage.
 as_recarray : boolean, default ``False``
-  DEPRECATED: this argument will be removed in a future version. Please call
-  ``pd.read_csv(...).to_records()`` instead.
+  .. deprecated:: 0.18.2
+     Please call ``pd.read_csv(...).to_records()`` instead.
 
   Return a NumPy recarray instead of a DataFrame after parsing the data. If
   set to ``True``, this option takes precedence over the ``squeeze`` parameter.
@@ -191,7 +191,8 @@ skiprows : list-like or integer, default ``None``
 skipfooter : int, default ``0``
   Number of lines at bottom of file to skip (unsupported with engine='c').
 skip_footer : int, default ``0``
-  DEPRECATED: use the ``skipfooter`` parameter instead, as they are identical
+  .. deprecated:: 0.19.0
+     Use the ``skipfooter`` parameter instead, as they are identical
 nrows : int, default ``None``
   Number of rows of file to read. Useful for reading pieces of large files.
 low_memory : boolean, default ``True``
@@ -202,16 +203,18 @@ low_memory : boolean, default ``True``
   use the ``chunksize`` or ``iterator`` parameter to return the data in chunks.
   (Only valid with C parser)
 buffer_lines : int, default None
-    DEPRECATED: this argument will be removed in a future version because its
-    value is not respected by the parser
+  .. deprecated:: 0.19.0
+     Argument removed because its value is not respected by the parser
 compact_ints : boolean, default False
-  DEPRECATED: this argument will be removed in a future version
+  .. deprecated:: 0.19.0
+     Argument moved to ``pd.to_numeric``
 
   If ``compact_ints`` is ``True``, then for any column that is of integer dtype, the
   parser will attempt to cast it as the smallest integer ``dtype`` possible, either
   signed or unsigned depending on the specification from the ``use_unsigned`` parameter.
 use_unsigned : boolean, default False
-  DEPRECATED: this argument will be removed in a future version
+  .. deprecated:: 0.18.2
+     Argument moved to ``pd.to_numeric``
 
   If integer columns are being compacted (i.e. ``compact_ints=True``), specify whether
   the column should be compacted to the smallest signed or unsigned integer dtype.
diff --git a/doc/sphinxext/numpydoc/README.rst b/doc/sphinxext/numpydoc/README.rst
index 89b9f2fd23e9b..eff87a4473e56 100755
--- a/doc/sphinxext/numpydoc/README.rst
+++ b/doc/sphinxext/numpydoc/README.rst
@@ -46,6 +46,8 @@ The following options can be set in conf.py:
   methods and attributes. If a table of contents is made, Sphinx expects
   each entry to have a separate page.
 
-- numpydoc_edit_link: bool  (DEPRECATED -- edit your HTML template instead)
+- numpydoc_edit_link: bool
+    .. deprecated::
+       Edit your HTML template instead
 
   Whether to insert an edit link after docstrings.
diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx
index c471d46262484..28e7d02819d44 100644
--- a/pandas/_libs/tslib.pyx
+++ b/pandas/_libs/tslib.pyx
@@ -1148,7 +1148,8 @@ cdef class _Timestamp(datetime):
 
     cpdef datetime to_datetime(_Timestamp self):
         """
-        DEPRECATED: use :meth:`to_pydatetime` instead.
+        .. deprecated:: 0.19.0
+           Use :meth:`to_pydatetime` instead.
 
         Convert a Timestamp object to a native Python datetime object.
         """
diff --git a/pandas/core/categorical.py b/pandas/core/categorical.py
index 5b663f1d85ee7..83b3852a8eef8 100644
--- a/pandas/core/categorical.py
+++ b/pandas/core/categorical.py
@@ -391,8 +391,8 @@ def itemsize(self):
 
     def reshape(self, new_shape, *args, **kwargs):
         """
-        DEPRECATED: calling this method will raise an error in a
-        future release.
+        .. deprecated:: 0.19.0
+           Calling this method will raise an error in a future release.
 
         An ndarray-compatible method that returns `self` because
         `Categorical` instances cannot actually be reshaped.
@@ -423,7 +423,8 @@ def base(self):
     @classmethod
     def from_array(cls, data, **kwargs):
         """
-        DEPRECATED: Use ``Categorical`` instead.
+        .. deprecated:: 0.19.0
+           Use ``Categorical`` instead.
 
         Make a Categorical type from a single array-like object.
 
@@ -1442,8 +1443,9 @@ def _values_for_rank(self):
 
     def order(self, inplace=False, ascending=True, na_position='last'):
         """
-        DEPRECATED: use :meth:`Categorical.sort_values`. That function
-        is entirely equivalent to this one.
+        .. deprecated:: 0.18.1
+           Use :meth:`Categorical.sort_values`. That function
+           is entirely equivalent to this one.
 
         See Also
         --------
@@ -1456,10 +1458,11 @@ def order(self, inplace=False, ascending=True, na_position='last'):
 
     def sort(self, inplace=True, ascending=True, na_position='last', **kwargs):
         """
-        DEPRECATED: use :meth:`Categorical.sort_values`. That function
-        is just like this one, except that a new Categorical is returned
-        by default, so make sure to pass in 'inplace=True' to get
-        inplace sorting.
+        .. deprecated:: 0.18.1
+           Use :meth:`Categorical.sort_values`. That function
+           is just like this one, except that a new Categorical is returned
+           by default, so make sure to pass in 'inplace=True' to get
+           inplace sorting.
 
         See Also
         --------
diff --git a/pandas/core/common.py b/pandas/core/common.py
index 0dc6a7a1e9c7b..5e66f913c2930 100644
--- a/pandas/core/common.py
+++ b/pandas/core/common.py
@@ -548,7 +548,8 @@ def in_qtconsole():
     """
     check if we're inside an IPython qtconsole
 
-    DEPRECATED: This is no longer needed, or working, in IPython 3 and above.
+    .. deprecated:: 0.14.1
+       This is no longer needed, or working, in IPython 3 and above.
     """
     try:
         ip = get_ipython()  # noqa
@@ -566,8 +567,8 @@ def in_ipnb():
     """
     check if we're inside an IPython Notebook
 
-    DEPRECATED: This is no longer used in pandas, and won't work in IPython 3
-    and above.
+    .. deprecated:: 0.14.1
+       This is no longer needed, or working, in IPython 3 and above.
     """
     try:
         ip = get_ipython()  # noqa
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index 48cb1ca2ebd2a..26d1b4c070c77 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -3477,7 +3477,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
     def sortlevel(self, level=0, axis=0, ascending=True, inplace=False,
                   sort_remaining=True):
         """
-        DEPRECATED: use :meth:`DataFrame.sort_index`
+        .. deprecated:: 0.20.0
+           Use :meth:`DataFrame.sort_index`
 
         Sort multilevel index by chosen axis and primary level. Data will be
         lexicographically sorted by the chosen level followed by the other
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
index da79912f7bd9e..0c47aad734c6d 100644
--- a/pandas/core/generic.py
+++ b/pandas/core/generic.py
@@ -1322,9 +1322,9 @@ def to_sql(self, name, con, flavor=None, schema=None, if_exists='fail',
             Using SQLAlchemy makes it possible to use any DB supported by that
             library. If a DBAPI2 object, only sqlite3 is supported.
         flavor : 'sqlite', default None
-            DEPRECATED: this parameter will be removed in a future version,
-            as 'sqlite' is the only supported option if SQLAlchemy is not
-            installed.
+            .. deprecated:: 0.19.0
+               'sqlite' is the only supported option if SQLAlchemy is not
+               installed.
         schema : string, default None
             Specify the schema (if database flavor supports this). If None, use
             default schema.
@@ -3162,7 +3162,8 @@ def _consolidate(self, inplace=False):
 
     def consolidate(self, inplace=False):
         """
-        DEPRECATED: consolidate will be an internal implementation only.
+        .. deprecated:: 0.20.0
+           Consolidate will be an internal implementation only.
         """
         # 15483
         warnings.warn("consolidate is deprecated and will be removed in a "
@@ -3373,7 +3374,9 @@ def astype(self, dtype, copy=True, errors='raise', **kwargs):
 
             .. versionadded:: 0.20.0
 
-        raise_on_error : DEPRECATED use ``errors`` instead
+        raise_on_error : raise on invalid input
+            .. deprecated:: 0.20.0
+               Use ``errors`` instead
         kwargs : keyword arguments to pass on to the constructor
 
         Returns
@@ -3476,7 +3479,7 @@ def _convert(self, datetime=False, numeric=False, timedelta=False,
     def convert_objects(self, convert_dates=True, convert_numeric=False,
                         convert_timedeltas=True, copy=True):
         """
-        Deprecated.
+        .. deprecated:: 0.18.0
 
         Attempt to infer better dtype for object columns
 
@@ -5684,8 +5687,9 @@ def tz_localize(self, tz, axis=0, level=None, copy=True,
             - 'NaT' will return NaT where there are ambiguous times
             - 'raise' will raise an AmbiguousTimeError if there are ambiguous
               times
-        infer_dst : boolean, default False (DEPRECATED)
-            Attempt to infer fall dst-transition hours based on order
+        infer_dst : boolean, default False
+            .. deprecated:: 0.15.0
+               Attempt to infer fall dst-transition hours based on order
 
         Returns
         -------
diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index 2af4f112ca941..a61897cf2c603 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -1008,7 +1008,8 @@ def _to_safe_for_reshape(self):
 
     def to_datetime(self, dayfirst=False):
         """
-        DEPRECATED: use :meth:`pandas.to_datetime` instead.
+        .. deprecated:: 0.19.0
+           Use :meth:`pandas.to_datetime` instead.
 
         For an Index containing strings or datetime.datetime objects, attempt
         conversion to DatetimeIndex
diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py
index ec678b1577d81..3a80355e82261 100644
--- a/pandas/core/indexes/datetimes.py
+++ b/pandas/core/indexes/datetimes.py
@@ -197,8 +197,9 @@ class DatetimeIndex(DatelikeOps, TimelikeOps, DatetimeIndexOpsMixin,
           times)
         - 'NaT' will return NaT where there are ambiguous times
         - 'raise' will raise an AmbiguousTimeError if there are ambiguous times
-    infer_dst : boolean, default False (DEPRECATED)
-        Attempt to infer fall dst-transition hours based on order
+    infer_dst : boolean, default False
+        .. deprecated:: 0.15.0
+           Attempt to infer fall dst-transition hours based on order
     name : object
         Name to be stored in the index
 
@@ -1818,8 +1819,9 @@ def tz_localize(self, tz, ambiguous='raise', errors='raise'):
 
             .. versionadded:: 0.19.0
 
-        infer_dst : boolean, default False (DEPRECATED)
-            Attempt to infer fall dst-transition hours based on order
+        infer_dst : boolean, default False
+            .. deprecated:: 0.15.0
+               Attempt to infer fall dst-transition hours based on order
 
         Returns
         -------
diff --git a/pandas/core/indexes/period.py b/pandas/core/indexes/period.py
index 15fd9b7dc2b6a..fb9002d34ccd2 100644
--- a/pandas/core/indexes/period.py
+++ b/pandas/core/indexes/period.py
@@ -566,7 +566,8 @@ def asfreq(self, freq=None, how='E'):
 
     def to_datetime(self, dayfirst=False):
         """
-        DEPRECATED: use :meth:`to_timestamp` instead.
+        .. deprecated:: 0.19.0
+           Use :meth:`to_timestamp` instead.
 
         Cast to DatetimeIndex.
         """
diff --git a/pandas/core/panel4d.py b/pandas/core/panel4d.py
index f32de29c5c167..16e7d0dfcc336 100644
--- a/pandas/core/panel4d.py
+++ b/pandas/core/panel4d.py
@@ -19,10 +19,10 @@
     having 4 named dimensions. It is intended as a test bed for more
     N-Dimensional named containers.
 
-    DEPRECATED. Panel4D is deprecated and will be removed in a future version.
-    The recommended way to represent these types of n-dimensional data are with
-    the `xarray package <http://xarray.pydata.org/en/stable/>`__.
-    Pandas provides a `.to_xarray()` method to automate this conversion.
+    .. deprecated:: 0.19.0
+       The recommended way to represent these types of n-dimensional data
+       are with the `xarray package <http://xarray.pydata.org/en/stable/>`__.
+       Pandas provides a `.to_xarray()` method to automate this conversion.
 
     Parameters
     ----------
diff --git a/pandas/core/panelnd.py b/pandas/core/panelnd.py
index 26ceeea654e4e..7a5cb63cd4f07 100644
--- a/pandas/core/panelnd.py
+++ b/pandas/core/panelnd.py
@@ -9,10 +9,10 @@ def create_nd_panel_factory(klass_name, orders, slices, slicer, aliases=None,
                             stat_axis=2, info_axis=0, ns=None):
     """ manufacture a n-d class:
 
-    DEPRECATED. Panelnd is deprecated and will be removed in a future version.
-    The recommended way to represent these types of n-dimensional data are with
-    the `xarray package <http://xarray.pydata.org/en/stable/>`__.
-    Pandas provides a `.to_xarray()` method to automate this conversion.
+    .. deprecated:: 0.19.0
+       The recommended way to represent these types of n-dimensional data
+       are with the `xarray package <http://xarray.pydata.org/en/stable/>`__.
+       Pandas provides a `.to_xarray()` method to automate this conversion.
 
     Parameters
     ----------
diff --git a/pandas/core/series.py b/pandas/core/series.py
index 129f291e5f843..4dfe07aae0eb4 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -850,8 +850,9 @@ def repeat(self, repeats, *args, **kwargs):
 
     def reshape(self, *args, **kwargs):
         """
-        DEPRECATED: calling this method will raise an error in a
-        future release. Please call ``.values.reshape(...)`` instead.
+        .. deprecated:: 0.19.0
+           Calling this method will raise an error. Please call
+           ``.values.reshape(...)`` instead.
 
         return an ndarray with the values shape
         if the specified shape matches exactly the current shape, then
@@ -1940,7 +1941,8 @@ def nsmallest(self, n=5, keep='first'):
 
     def sortlevel(self, level=0, ascending=True, sort_remaining=True):
         """
-        DEPRECATED: use :meth:`Series.sort_index`
+        .. deprecated:: 0.20.0
+           Use :meth:`Series.sort_index`
 
         Sort Series with MultiIndex by chosen level. Data will be
         lexicographically sorted by the chosen level followed by the other
diff --git a/pandas/core/sparse/array.py b/pandas/core/sparse/array.py
index 8ac9d3916573e..bdcec990cfe2c 100644
--- a/pandas/core/sparse/array.py
+++ b/pandas/core/sparse/array.py
@@ -391,8 +391,8 @@ def to_dense(self, fill=None):
         Parameters
         ----------
         fill: float, default None
-            DEPRECATED: this argument will be removed in a future version
-            because it is not respected by this function.
+            .. deprecated:: 0.20.0
+               This argument is not respected by this function.
 
         Returns
         -------
diff --git a/pandas/core/strings.py b/pandas/core/strings.py
index c57d7a9362490..fa68b61f7cf3f 100644
--- a/pandas/core/strings.py
+++ b/pandas/core/strings.py
@@ -478,7 +478,10 @@ def str_match(arr, pat, case=True, flags=0, na=np.nan, as_indexer=None):
     flags : int, default 0 (no flags)
         re module flags, e.g. re.IGNORECASE
     na : default NaN, fill value for missing values.
-    as_indexer : DEPRECATED
+    as_indexer : False, by default, gives deprecated behavior better
+        achieved using str_extract. True return boolean indexer.
+        .. deprecated:: 0.20.0
+           Keyword is ignored
 
     Returns
     -------
diff --git a/pandas/core/window.py b/pandas/core/window.py
index cf1bad706ae1d..d8c362b454f79 100644
--- a/pandas/core/window.py
+++ b/pandas/core/window.py
@@ -341,21 +341,23 @@ def aggregate(self, arg, *args, **kwargs):
 
     Parameters
     ----------
-    how : string, default None (DEPRECATED)
-        Method for down- or re-sampling""")
+    how : string, default None
+        .. deprecated:: 0.18.0
+           Method for down- or re-sampling""")
 
     _shared_docs['mean'] = dedent("""
     %(name)s mean
 
     Parameters
     ----------
-    how : string, default None (DEPRECATED)
-        Method for down- or re-sampling""")
+    how : string, default None
+        .. deprecated:: 0.18.0
+           Method for down- or re-sampling""")
 
 
 class Window(_Window):
     """
-    Provides rolling window calculcations.
+    Provides rolling window calculations.
 
     .. versionadded:: 0.18.0
 
@@ -373,9 +375,10 @@ class Window(_Window):
         Minimum number of observations in window required to have a value
         (otherwise result is NA). For a window that is specified by an offset,
         this will default to 1.
-    freq : string or DateOffset object, optional (default None) (DEPRECATED)
-        Frequency to conform the data to before computing the statistic.
-        Specified as a frequency string or DateOffset object.
+    freq : string or DateOffset object, optional (default None)
+        .. deprecated:: 0.18.0
+           Frequency to conform the data to before computing the statistic.
+           Specified as a frequency string or DateOffset object.
     center : boolean, default False
         Set the labels at the center of the window.
     win_type : string, default None
@@ -570,8 +573,9 @@ def _apply_window(self, mean=True, how=None, **kwargs):
         ----------
         mean : boolean, default True
             If True computes weighted mean, else weighted sum
-        how : string, default to None (DEPRECATED)
-            how to resample
+        how : string, default to None
+            .. deprecated:: 0.18.0
+               how to resample
 
         Returns
         -------
@@ -735,8 +739,9 @@ def _apply(self, func, name=None, window=None, center=None,
         window : int/array, default to _get_window()
         center : boolean, default to self.center
         check_minp : function, default to _use_window
-        how : string, default to None (DEPRECATED)
-            how to resample
+        how : string, default to None
+            .. deprecated:: 0.18.0
+               how to resample
 
         Returns
         -------
@@ -863,8 +868,9 @@ def sum(self, *args, **kwargs):
 
     Parameters
     ----------
-    how : string, default 'max' (DEPRECATED)
-        Method for down- or re-sampling""")
+    how : string, default 'max'
+        .. deprecated:: 0.18.0
+           Method for down- or re-sampling""")
 
     def max(self, how=None, *args, **kwargs):
         nv.validate_window_func('max', args, kwargs)
@@ -877,8 +883,9 @@ def max(self, how=None, *args, **kwargs):
 
     Parameters
     ----------
-    how : string, default 'min' (DEPRECATED)
-        Method for down- or re-sampling""")
+    how : string, default 'min'
+        .. deprecated:: 0.18.0
+           Method for down- or re-sampling""")
 
     def min(self, how=None, *args, **kwargs):
         nv.validate_window_func('min', args, kwargs)
@@ -895,8 +902,9 @@ def mean(self, *args, **kwargs):
 
     Parameters
     ----------
-    how : string, default 'median' (DEPRECATED)
-        Method for down- or re-sampling""")
+    how : string, default 'median'
+        .. deprecated:: 0.18.0
+           Method for down- or re-sampling""")
 
     def median(self, how=None, **kwargs):
         if self.freq is not None and how is None:
@@ -1322,9 +1330,10 @@ class Expanding(_Rolling_and_Expanding):
     min_periods : int, default None
         Minimum number of observations in window required to have a value
         (otherwise result is NA).
-    freq : string or DateOffset object, optional (default None) (DEPRECATED)
-        Frequency to conform the data to before computing the statistic.
-        Specified as a frequency string or DateOffset object.
+    freq : string or DateOffset object, optional (default None)
+        .. deprecated:: 0.18.0
+           Frequency to conform the data to before computing the statistic.
+           Specified as a frequency string or DateOffset object.
     center : boolean, default False
         Set the labels at the center of the window.
     axis : int or string, default 0
@@ -1586,8 +1595,9 @@ class EWM(_Rolling):
     min_periods : int, default 0
         Minimum number of observations in window required to have a value
         (otherwise result is NA).
-    freq : None or string alias / date offset object, default=None (DEPRECATED)
-        Frequency to conform to before computing statistic
+    freq : None or string alias / date offset object, default=None
+        .. deprecated:: 0.18.0
+           Frequency to conform to before computing statistic
     adjust : boolean, default True
         Divide by decaying adjustment factor in beginning periods to account
         for imbalance in relative weightings (viewing EWMA as a moving average)
@@ -1720,8 +1730,9 @@ def _apply(self, func, how=None, **kwargs):
         Parameters
         ----------
         func : string/callable to apply
-        how : string, default to None (DEPRECATED)
-            how to resample
+        how : string, default to None
+            .. deprecated:: 0.18.0
+               how to resample
 
         Returns
         -------
diff --git a/pandas/io/excel.py b/pandas/io/excel.py
index 81a36b21b3617..e4f5655b47411 100644
--- a/pandas/io/excel.py
+++ b/pandas/io/excel.py
@@ -141,9 +141,10 @@
     data will be read in as floats: Excel stores all numbers as floats
     internally
 has_index_names : boolean, default None
-    DEPRECATED: for version 0.17+ index names will be automatically
-    inferred based on index_col.  To read Excel output from 0.16.2 and
-    prior that had saved index names, use True.
+    .. deprecated:: 0.17.0
+       For version 0.17+ index names will be automatically
+       inferred based on index_col.  To read Excel output from 0.16.2 and
+       prior that had saved index names, use True.
 
 Returns
 -------
diff --git a/pandas/io/parsers.py b/pandas/io/parsers.py
index e287d92f67ef6..91175bf178d48 100755
--- a/pandas/io/parsers.py
+++ b/pandas/io/parsers.py
@@ -105,8 +105,8 @@
     ['AAA', 'BBB', 'DDD']``. Using this parameter results in much faster
     parsing time and lower memory usage.
 as_recarray : boolean, default False
-    DEPRECATED: this argument will be removed in a future version. Please call
-    `pd.read_csv(...).to_records()` instead.
+    .. deprecated:: 0.19.0
+       Please call `pd.read_csv(...).to_records()` instead.
 
     Return a NumPy recarray instead of a DataFrame after parsing the data.
     If set to True, this option takes precedence over the `squeeze` parameter.
@@ -145,7 +145,8 @@
 skipfooter : int, default 0
     Number of lines at bottom of file to skip (Unsupported with engine='c')
 skip_footer : int, default 0
-    DEPRECATED: use the `skipfooter` parameter instead, as they are identical
+    .. deprecated:: 0.19.0
+       Use the `skipfooter` parameter instead, as they are identical
 nrows : int, default None
     Number of rows of file to read. Useful for reading pieces of large files
 na_values : scalar, str, list-like, or dict, default None
@@ -276,17 +277,19 @@
     use the `chunksize` or `iterator` parameter to return the data in chunks.
     (Only valid with C parser)
 buffer_lines : int, default None
-    DEPRECATED: this argument will be removed in a future version because its
-    value is not respected by the parser
+    .. deprecated:: 0.19.0
+       This argument is not respected by the parser
 compact_ints : boolean, default False
-    DEPRECATED: this argument will be removed in a future version
+    .. deprecated:: 0.19.0
+       Argument moved to ``pd.to_numeric``
 
     If compact_ints is True, then for any column that is of integer dtype,
     the parser will attempt to cast it as the smallest integer dtype possible,
     either signed or unsigned depending on the specification from the
     `use_unsigned` parameter.
 use_unsigned : boolean, default False
-    DEPRECATED: this argument will be removed in a future version
+    .. deprecated:: 0.19.0
+       Argument moved to ``pd.to_numeric``
 
     If integer columns are being compacted (i.e. `compact_ints=True`), specify
     whether the column should be compacted to the smallest signed or unsigned
diff --git a/pandas/io/sql.py b/pandas/io/sql.py
index ee992c6dd3439..8fb28d2dedc68 100644
--- a/pandas/io/sql.py
+++ b/pandas/io/sql.py
@@ -432,7 +432,9 @@ def to_sql(frame, name, con, flavor=None, schema=None, if_exists='fail',
         library.
         If a DBAPI2 object, only sqlite3 is supported.
     flavor : 'sqlite', default None
-        DEPRECATED: this parameter will be removed in a future version
+        .. deprecated:: 0.19.0
+           'sqlite' is the only supported option if SQLAlchemy is not
+           installed.
     schema : string, default None
         Name of SQL schema in database to write to (if database flavor
         supports this). If None, use default schema (default).
@@ -484,7 +486,9 @@ def has_table(table_name, con, flavor=None, schema=None):
         library.
         If a DBAPI2 object, only sqlite3 is supported.
     flavor : 'sqlite', default None
-        DEPRECATED: this parameter will be removed in a future version
+        .. deprecated:: 0.19.0
+           'sqlite' is the only supported option if SQLAlchemy is not
+           installed.
     schema : string, default None
         Name of SQL schema in database to write to (if database flavor supports
         this). If None, use default schema (default).
@@ -1545,7 +1549,9 @@ def get_schema(frame, name, flavor=None, keys=None, con=None, dtype=None):
         library, default: None
         If a DBAPI2 object, only sqlite3 is supported.
     flavor : 'sqlite', default None
-        DEPRECATED: this parameter will be removed in a future version
+        .. deprecated:: 0.19.0
+           'sqlite' is the only supported option if SQLAlchemy is not
+           installed.
     dtype : dict of column name to SQL type, default None
         Optional specifying the datatype for columns. The SQL type should
         be a SQLAlchemy type, or a string for sqlite3 fallback connection.
diff --git a/pandas/io/stata.py b/pandas/io/stata.py
index e03e87f09173e..107dccfc8175c 100644
--- a/pandas/io/stata.py
+++ b/pandas/io/stata.py
@@ -110,9 +110,11 @@
        _statafile_processing_params2, _chunksize_params,
        _iterator_params)
 
-_data_method_doc = """Reads observations from Stata file, converting them into a dataframe
+_data_method_doc = """\
+Reads observations from Stata file, converting them into a dataframe
 
-This is a legacy method.  Use `read` in new code.
+    .. deprecated::
+       This is a legacy method.  Use `read` in new code.
 
 Parameters
 ----------
@@ -1407,7 +1409,7 @@ def _read_strls(self):
             self.GSO[str(v_o)] = va
 
     # legacy
-    @Appender('DEPRECATED: ' + _data_method_doc)
+    @Appender(_data_method_doc)
     def data(self, **kwargs):
 
         import warnings


Code review comments:
diff_hunk: @@ -1148,7 +1148,8 @@ cdef class _Timestamp(datetime):
 
     cpdef datetime to_datetime(_Timestamp self):
         """
-        DEPRECATED: use :meth:`to_pydatetime` instead.
+        .. deprecated:: 0.19.0
+           Use :meth:`to_pydatetime` instead.
path: pandas/_libs/tslib.pyx
text: @user1:
Can you leave this one as is? The thing is that the first sentence of the docstring gets added to the API overview. So the actual "DEPRECATED .. " is then more useful as the directive code (although I am actually not sure what sphinx would put in the api summary table)

@author:
It seems sphinx only parses the first line to the summary table as expected. The changes have been reverted to avoid losing information in the API summary table.

![screenshot from 2017-06-15 09-41-54](https://user-images.githubusercontent.com/10288252/27187953-991b8eea-51ba-11e7-9829-fb3d9808940e.png)