DOC: Fix swaplevel docstring

[TheNeuralBit]

• closes BUG: swaplevel docstring incorrectly indented at Examples #44739
• tests added / passed
• Ensure all linting tests pass, see here for how to run them
• whatsnew entry

[TheNeuralBit]

If possible (and if there's going to be a 1.3.5) I'd like to make this change on the 1.3 branch as well. Is there a process for that?

[phofl]

In general we do not backport doc fixes if they were not introduced on the release before

[jreback]

hmm something odd with the validation here, can you see if you can address this: https://github.com/pandas-dev/pandas/runs/4413823661?check_suite_focus=true

[jreback]

and this renders ok?

[TheNeuralBit]

Check failure https://github.com/pandas-dev/pandas/runs/4436214474?check_suite_focus=true looks like a flake. Could someone re-run?

[TheNeuralBit]

and this renders ok?

pd.Series.swaplevel:

Signature: pd.Series.swaplevel(self, i=-2, j=-1, copy=True) -> 'Series'
Docstring:
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.
copy : bool, default True
            Whether to copy underlying data.

Returns
-------
Series
    Series with levels swapped in MultiIndex.

Examples
--------
>>> s = pd.Series(
...     ["A", "B", "A", "C"],
...     index=[
...         ["Final exam", "Final exam", "Coursework", "Coursework"],
...         ["History", "Geography", "History", "Geography"],
...         ["January", "February", "March", "April"],
...     ],
... )
>>> s
Final exam  History     January      A
            Geography   February     B
Coursework  History     March        A
            Geography   April        C
dtype: object

...

pd.DataFrame.swaplevel?:

Signature:
pd.DataFrame.swaplevel(
    self,
    i: 'Axis' = -2,
    j: 'Axis' = -1,
    axis: 'Axis' = 0,
) -> 'DataFrame'
Docstring:
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.

Examples
--------
>>> df = pd.DataFrame(
...     {"Grade": ["A", "B", "A", "C"]},
...     index=[
...         ["Final exam", "Final exam", "Coursework", "Coursework"],
...         ["History", "Geography", "History", "Geography"],
...         ["January", "February", "March", "April"],
...     ],
... )

...

Series.swaplevel API Reference:

DataFrame.swaplevel API Reference:

[TheNeuralBit]

In general we do not backport doc fixes if they were not introduced on the release before

Sorry I'm not quite sure what you mean by this, the Examples section was introduced in the previous minor release (1.3.0). Do you mean this could only be backported to 1.3 if the doc regression was introduced in 1.2?

I'm not trying to push back too hard on this, I'll respect whatever you want to do here. Just trying to understand the policy

[jreback]

In general we do not backport doc fixes if they were not introduced on the release before

Sorry I'm not quite sure what you mean by this, the Examples section was introduced in the previous minor release (1.3.0). Do you mean this could only be backported to 1.3 if the doc regression was introduced in 1.2?

I'm not trying to push back too hard on this, I'll respect whatever you want to do here. Just trying to understand the policy

we only backport code change regressions, and 1.3.x is at an end.

[jreback]

thanks @TheNeuralBit