From 8330de28d1a67f3e6380b7624007b47a2e475ade Mon Sep 17 00:00:00 2001
From: Tuhin Sharma <tuhinsharma121@gmail.com>
Date: Mon, 6 May 2024 23:53:26 +0530
Subject: [PATCH] DOC: Enforce Numpy Docstring Validation for
 pandas.DataFrame.swaplevel (#58566)

* DOC: add SA01 for pandas.DataFrame.swaplevel

* DOC: remove SA01 for pandas.DataFrame.swaplevel
---
 ci/code_checks.sh    |  1 -
 pandas/core/frame.py | 40 ++++++++++++++++++++++++++--------------
 2 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/ci/code_checks.sh b/ci/code_checks.sh
index 32a7c85fb513c..00e8a10613f44 100755
--- a/ci/code_checks.sh
+++ b/ci/code_checks.sh
@@ -75,7 +75,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.DataFrame.median RT03,SA01" \
         -i "pandas.DataFrame.min RT03" \
         -i "pandas.DataFrame.plot PR02,SA01" \
-        -i "pandas.DataFrame.swaplevel SA01" \
         -i "pandas.Grouper PR02" \
         -i "pandas.Index PR07" \
         -i "pandas.Index.ravel PR01,RT03" \
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
index f0e956eb86c9a..39113cda8b232 100644
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -7642,16 +7642,30 @@ def nsmallest(
         """
         return selectn.SelectNFrame(self, n=n, keep=keep, columns=columns).nsmallest()
 
-    @doc(
-        Series.swaplevel,
-        klass=_shared_doc_kwargs["klass"],
-        extra_params=dedent(
-            """axis : {0 or 'index', 1 or 'columns'}, default 0
-            The axis to swap levels on. 0 or 'index' for row-wise, 1 or
-            'columns' for column-wise."""
-        ),
-        examples=dedent(
-            """\
+    def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame:
+        """
+        Swap levels i and j in a :class:`MultiIndex`.
+
+        Default is to swap the two innermost levels of the index.
+
+        Parameters
+        ----------
+        i, j : int or str
+            Levels of the indices to be swapped. Can pass level name as string.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+                    The axis to swap levels on. 0 or 'index' for row-wise, 1 or
+                    'columns' for column-wise.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with levels swapped in MultiIndex.
+
+        See Also
+        --------
+        DataFrame.reorder_levels: Reorder levels of MultiIndex.
+        DataFrame.sort_index: Sort MultiIndex.
+
         Examples
         --------
         >>> df = pd.DataFrame(
@@ -7701,10 +7715,8 @@ def nsmallest(
         History     Final exam  January         A
         Geography   Final exam  February        B
         History     Coursework  March           A
-        Geography   Coursework  April           C"""
-        ),
-    )
-    def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame:
+        Geography   Coursework  April           C
+        """
         result = self.copy(deep=False)
 
         axis = self._get_axis_number(axis)