DOC: fix PR02 errors in docstring for pandas.Series.rename_axis (#57239)

* DOC: fix PR02 errors in docstring for pandas.Series.rename_axis * Refactor Series.rename_axis and NDFrame.rename_axis to have separate docstrings * removed unnecessary columns ref in docstring for Series * removed another unnecessary columns ref in docstring for Series
pandas-dev · Feb 4, 2024 · 266bd4c · 266bd4c
1 parent a28de76
commit 266bd4c
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 25 deletions.
diff --git a/ci/code_checks.sh b/ci/code_checks.sh
@@ -91,7 +91,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.TimedeltaIndex.floor\
         pandas.TimedeltaIndex.ceil\
         pandas.PeriodIndex.strftime\
-        pandas.Series.rename_axis\
         pandas.Series.dt.to_period\
         pandas.Series.dt.tz_localize\
         pandas.Series.dt.tz_convert\

diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -1158,18 +1158,18 @@ def rename_axis(
         ----------
         mapper : scalar, list-like, optional
             Value to set the axis name attribute.
-        index, columns : scalar, list-like, dict-like or function, optional
-            A scalar, list-like, dict-like or functions transformations to
-            apply to that axis' values.
-            Note that the ``columns`` parameter is not allowed if the
-            object is a Series. This parameter only apply for DataFrame
-            type objects.
 
             Use either ``mapper`` and ``axis`` to
             specify the axis to target with ``mapper``, or ``index``
             and/or ``columns``.
+        index : scalar, list-like, dict-like or function, optional
+            A scalar, list-like, dict-like or functions transformations to
+            apply to that axis' values.
+        columns : scalar, list-like, dict-like or function, optional
+            A scalar, list-like, dict-like or functions transformations to
+            apply to that axis' values.
         axis : {0 or 'index', 1 or 'columns'}, default 0
-            The axis to rename. For `Series` this parameter is unused and defaults to 0.
+            The axis to rename.
         copy : bool, default None
             Also copy underlying data.
 
@@ -1190,7 +1190,7 @@ def rename_axis(
 
         Returns
         -------
-        Series, DataFrame, or None
+        DataFrame, or None
             The same type as the caller or None if ``inplace=True``.
 
         See Also
@@ -1220,21 +1220,6 @@ def rename_axis(
 
         Examples
         --------
-        **Series**
-
-        >>> s = pd.Series(["dog", "cat", "monkey"])
-        >>> s
-        0       dog
-        1       cat
-        2    monkey
-        dtype: object
-        >>> s.rename_axis("animal")
-        animal
-        0    dog
-        1    cat
-        2    monkey
-        dtype: object
-
         **DataFrame**
 
         >>> df = pd.DataFrame({"num_legs": [4, 4, 2],

diff --git a/pandas/core/series.py b/pandas/core/series.py
@@ -5041,7 +5041,6 @@ def rename_axis(
     ) -> Self | None:
         ...
 
-    @doc(NDFrame.rename_axis)
     def rename_axis(
         self,
         mapper: IndexLabel | lib.NoDefault = lib.no_default,
@@ -5051,6 +5050,67 @@ def rename_axis(
         copy: bool = True,
         inplace: bool = False,
     ) -> Self | None:
+        """
+        Set the name of the axis for the index.
+
+        Parameters
+        ----------
+        mapper : scalar, list-like, optional
+            Value to set the axis name attribute.
+
+            Use either ``mapper`` and ``axis`` to
+            specify the axis to target with ``mapper``, or ``index``.
+
+        index : scalar, list-like, dict-like or function, optional
+            A scalar, list-like, dict-like or functions transformations to
+            apply to that axis' values.
+        axis : {0 or 'index'}, default 0
+            The axis to rename. For `Series` this parameter is unused and defaults to 0.
+        copy : bool, default None
+            Also copy underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        inplace : bool, default False
+            Modifies the object directly, instead of creating a new Series
+            or DataFrame.
+
+        Returns
+        -------
+        Series, or None
+            The same type as the caller or None if ``inplace=True``.
+
+        See Also
+        --------
+        Series.rename : Alter Series index labels or name.
+        DataFrame.rename : Alter DataFrame index labels or name.
+        Index.rename : Set new names on index.
+
+        Examples
+        --------
+
+        >>> s = pd.Series(["dog", "cat", "monkey"])
+        >>> s
+        0       dog
+        1       cat
+        2    monkey
+        dtype: object
+        >>> s.rename_axis("animal")
+        animal
+        0    dog
+        1    cat
+        2    monkey
+        dtype: object
+        """
         return super().rename_axis(
             mapper=mapper,
             index=index,