Add examples to documentation for DataFrame.swaplevel

[thordisstella]

• [x ] closes add example to swaplevel MarcoGorelli/pyladieslondon-sprints#13
• tests added / passed
• Ensure all linting tests pass, see here for how to run them
• whatsnew entry

[pep8speaks]

Hello @thordisstella! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2021-03-11 20:58:01 UTC

[MarcoGorelli]

Really nice example @thordisstella , thanks, have just left some minor comments

[MarcoGorelli]

can you leave a blank line before this?

[MarcoGorelli]

Could you reformat this according to the black formatter (to be consistent with most of the rest of the docs...we should probably run blackdoc, but that's for a separate issue/PR)

[MarcoGorelli]

can you add a space between the arguments? (swaplevel(0, 1))

[thordisstella]

Really nice example @thordisstella , thanks, have just left some minor comments

Thanks for the review @MarcoGorelli! I addressed the comments, but when I ran black on the changes I'd made, nothing further was updated (after I'd addressed your other two comments). Please let me know if I've missed something here

[MarcoGorelli]

Hey @thordisstella , thanks for updating (and happy IWD!)! Sorry, I was unclear - black indeed won't modify what you've written, because it doesn't format code inside docstrings (barring some very minor things). I was suggesting to reformat the docstring the way that black would - one way to do this would be to paste the docstring into a temporary file (say, t.py):

# t.py

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

, running

pip install blackdoc
blackdoc t.py --line-length 80

and then pasting the reformatted version back into this docstring of swaplevel

Finally, you should run

$ python scripts/validate_docstrings.py pandas.DataFrame.swaplevel

and check it doesn't throw any extra errors compared to when run on master (in this case you prob. just need to reformat the code in the example and remove the extra blankline at the end of the docstring)

[thordisstella]

Thanks, and belated happy IWD to you too! 😊

Thanks for the clarification - I've updated the PR as you suggested so hopefully we should be good now 🤞

[MarcoGorelli]

Thanks - there's just a blank line which needs removing (else it'll fail scripts/validate_docstrings.py), rest looks good

[MarcoGorelli]

Suggested change

	Geography Coursework April C
	"""
	Geography Coursework April C
	"""

[MarcoGorelli]

Hi @thordisstella - looks good, CI failures should be unrelated, could you fetch and merge upstream/master please?

[MarcoGorelli]

Pending green, looks good to me!

(a follow-up PR to add a similar example to Series.swaplevel and/or make a shared docstring would be welcome if you want)

[thordisstella]

Thanks for the review, all the advice and for merging this @MarcoGorelli ! And apologies for the delay in reacting to your last comment. I'll take a look at the follow up PR you suggested either later this week or next week :)