DOC removed unnecessary use of parameter in example rename function call (#26250)

* DOC removed unnecessary use of parameter in example rename function call

removed unnecessary (and misleading) use of index parameter in docstring example function call of rename function

* DOC added examples as discussed in the pull request review

added an example for using index parameter only
added an example for casting the index type

* DOC fixed line to long

* DOC fixed doctest fail because of unexpected linebreak

* DOC simplified examples

* DOC fixed the examples matching the output mentioned in the doc

* DOC terminology change

Author: KatemaNL

pandas/core/frame.py

@@ -3995,20 +3995,28 @@ def rename(self, *args, **kwargs):
         We *highly* recommend using keyword arguments to clarify your
         intent.
 
+        Rename columns using a mapping:
         >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
-        >>> df.rename(index=str, columns={"A": "a", "B": "c"})
+        >>> df.rename(columns={"A": "a", "B": "c"})
            a  c
         0  1  4
         1  2  5
         2  3  6
 
-        >>> df.rename(index=str, columns={"A": "a", "C": "c"})
-           a  B
-        0  1  4
-        1  2  5
-        2  3  6
+        Rename index using a mapping:
+        >>> df.rename(index={0: "x", 1: "y", 2: "z"})
+           A  B
+        x  1  4
+        y  2  5
+        z  3  6
+
+        Cast index labels to a different type:
+        >>> df.index
+        RangeIndex(start=0, stop=3, step=1)
+        >>> df.rename(index=str).index
+        Index(['0', '1', '2'], dtype='object')
 
-        >>> df.rename(index=str, columns={"A": "a", "C": "c"}, errors="raise")
+        >>> df.rename(columns={"A": "a", "B": "b", "C": "c"}, errors="raise")
         Traceback (most recent call last):
         KeyError: ['C'] not found in axis