Backport PR #41968 on branch 1.3.x (DOC: 1.3.0 release notes addition and doc fix)

doc/source/reference/style.rst

@@ -34,7 +34,6 @@ Style application
 
    Styler.apply
    Styler.applymap
-   Styler.where
    Styler.format
    Styler.set_td_classes
    Styler.set_table_styles

doc/source/whatsnew/v1.3.0.rst

@@ -812,6 +812,7 @@ Other Deprecations
 - Using ``.astype`` to convert between ``datetime64[ns]`` dtype and :class:`DatetimeTZDtype` is deprecated and will raise in a future version, use ``obj.tz_localize`` or ``obj.dt.tz_localize`` instead (:issue:`38622`)
 - Deprecated casting ``datetime.date`` objects to ``datetime64`` when used as ``fill_value`` in :meth:`DataFrame.unstack`, :meth:`DataFrame.shift`, :meth:`Series.shift`, and :meth:`DataFrame.reindex`, pass ``pd.Timestamp(dateobj)`` instead (:issue:`39767`)
 - Deprecated :meth:`.Styler.set_na_rep` and :meth:`.Styler.set_precision` in favour of :meth:`.Styler.format` with ``na_rep`` and ``precision`` as existing and new input arguments respectively (:issue:`40134`, :issue:`40425`)
+- Deprecated :meth:`.Styler.where` in favour of using an alternative formulation with :meth:`Styler.applymap` (:issue:`40821`)
 - Deprecated allowing partial failure in :meth:`Series.transform` and :meth:`DataFrame.transform` when ``func`` is list-like or dict-like and raises anything but ``TypeError``; ``func`` raising anything but a ``TypeError`` will raise in a future version (:issue:`40211`)
 - Deprecated arguments ``error_bad_lines`` and ``warn_bad_lines`` in :meth:`read_csv` and :meth:`read_table` in favor of argument ``on_bad_lines`` (:issue:`15122`)
 - Deprecated support for ``np.ma.mrecords.MaskedRecords`` in the :class:`DataFrame` constructor, pass ``{name: data[name] for name in data.dtype.names}`` instead (:issue:`40363`)

pandas/io/formats/style.py

@@ -1206,12 +1206,14 @@ def where(
         recommend using instead.
 
         The example:
+
         >>> df = pd.DataFrame([[1, 2], [3, 4]])
         >>> def cond(v, limit=4):
         ...     return v > 1 and v != limit
         >>> df.style.where(cond, value='color:green;', other='color:red;')
 
         should be refactored to:
+
         >>> def style_func(v, value, other, limit=4):
         ...     cond = v > 1 and v != limit
         ...     return value if cond else other