DOC: Substitute example in DataFrame.to_markdown docstring (#42126)

[neinkeinkaffee]

• closes DOC DataFrame.to_markdown examples don't get substituted #42126
• tests added / passed
• Ensure all linting tests pass, see here for how to run them
• whatsnew entry

[MarcoGorelli]

Nice, thanks @neinkeinkaffee ! Did you try building these pages locally to check that they show up fine? If so, could you post a screenshot?

see here for how to build the docs locally, you'll probably want to use the --single option with pandas.DataFrame.to_markdown

[neinkeinkaffee]

Sure! This is how they look like:

[MarcoGorelli]

Thanks - From the first screenshot you posted (DataFrame.to_markdown), it looks like the Series example is still the one being substituted into the docstring 🤔

[neinkeinkaffee]

OMG, you're right, weird, I could swear it was alright when I checked earlier! Will check what happened there

[neinkeinkaffee]

Here it is one more time:

[MarcoGorelli]

Awesome, thanks (perhaps you hadn't done python make.py clean before starting?)

Looks good to me pending green

[attack68]

we could also add to_markdown to user_guide/io/rst. It recently had some output methods added, but I didn't even know this one existed.

[MarcoGorelli]

Good idea - @neinkeinkaffee if you wanted to do that (in a separate PR) it'd be welcome, else we can open it as an issue for others to take

CI failures here are probably unrelated, if you fetch and merge upstream/master once CI is fixed they'll probably be fine

[neinkeinkaffee]

@MarcoGorelli Sure, I'll add it to userguide/io.rst and submit a separate PR for that.

Regarding the failing CI check of this one, do you mean I should just merge my branch with master again and that might fix it?

[MarcoGorelli]

Yeah, that's right - latest PRs seem to be mostly green, so if you fetch and merge upstream/master now that might be enough

[neinkeinkaffee]

Updated with the most recent commits from master, hopefully that'll make the checks go green. I'll work on updating the io.rst on a separate branch.

[neinkeinkaffee]

Actually, having a second look at io.rst I see that the documentation for each of the read and write methods is quite extensive there, containing lots of tips and tricks. Not sure if I can come up with something like that for to_markdown on the spot, it looks like a bigger project to be honest :)

[MarcoGorelli]

No worries, I can open it up as an issue and someone else will take it! Thanks for your help on this one!

[MarcoGorelli]

@simonjayhawkins I've seen some recent docs PRs being tagged as 1.3, is that an OK milestone for this one too?

[MarcoGorelli]