DOC: Fixes DataFrame.replace documentation (#55762)

* fix replace docs

* fix replace docs

* move description to examples

* fix spacing

* fix dicts

* fix line size

* fix whitespace

* remove trailling whitespaces

* fix df

* fix df

* Update pandas/core/shared_docs.py

Co-authored-by: Matthew Roeschke <[email protected]>

* Update pandas/core/shared_docs.py

Co-authored-by: Matthew Roeschke <[email protected]>

---------

Co-authored-by: Matthew Roeschke <[email protected]>

Author: jpgianfaldoni

pandas/core/shared_docs.py

@@ -570,8 +570,7 @@
         .. deprecated:: 2.1.0
     regex : bool or same types as `to_replace`, default False
         Whether to interpret `to_replace` and/or `value` as regular
-        expressions. If this is ``True`` then `to_replace` *must* be a
-        string. Alternatively, this could be a regular expression or a
+        expressions. Alternatively, this could be a regular expression or a
         list, dict, or array of regular expressions in which case
         `to_replace` must be ``None``.
     method : {{'pad', 'ffill', 'bfill'}}
@@ -790,6 +789,32 @@
 
         .. versionchanged:: 1.4.0
             Previously the explicit ``None`` was silently ignored.
+
+    When ``regex=True``, ``value`` is not ``None`` and `to_replace` is a string,
+    the replacement will be applied in all columns of the DataFrame.
+
+    >>> df = pd.DataFrame({{'A': [0, 1, 2, 3, 4],
+    ...                    'B': ['a', 'b', 'c', 'd', 'e'],
+    ...                    'C': ['f', 'g', 'h', 'i', 'j']}})
+
+    >>> df.replace(to_replace='^[a-g]', value = 'e', regex=True)
+        A  B  C
+    0  0  e  e
+    1  1  e  e
+    2  2  e  h
+    3  3  e  i
+    4  4  e  j
+
+    If ``value`` is not ``None`` and `to_replace` is a dictionary, the dictionary
+    keys will be the DataFrame columns that the replacement will be applied.
+
+    >>> df.replace(to_replace={{'B': '^[a-c]', 'C': '^[h-j]'}}, value = 'e', regex=True)
+        A  B  C
+    0  0  e  f
+    1  1  e  g
+    2  2  e  e
+    3  3  d  e
+    4  4  e  e
 """
 
 _shared_docs[