DOC: The argument of pandas.DataFrame.to_markdown is unfriendly

[nuka137]

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.to_markdown.html

Documentation problem

The document of pandas.DataFrame.to_markdown is unfriendly because many options are shown as **kwargs.
I think these arguments should be documented explicitly like a to_csv.

https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.to_csv.html

Suggested fix for documentation

All arguments supported by to_markdown should be shown at document.
If don't mind, I would like to tackle this improvement.

[MarcoGorelli]

Thanks @nuka137 - there's a PR open to document 'index', if you'd like to document other options I think that would be welcome

[TomAugspurger]

I'd caution against adding too many keyword arguments. The function could be expanded in the future to accept an engine function to determine which package we use to format things.

So we should only add explicit keywords for names that are standard across the rest of pandas IO methods.

[nuka137]

@MarcoGorelli @TomAugspurger

Thanks!
I agree not to introduce many keywords too. But I didn't intend to add more keyword arguments in this issue.
This issue mentions the unclear documentation of **kwargs.

I think adding a link of tabulate package to this document is enough for the user.
Or, it may be good to add an example which uses tabulate argument.
The users can check what options they need to pass to **kwargs.
What do you think of this idea?

[TomAugspurger]

Thanks, both of those sound like great ideas.

…

On Thu, Jun 4, 2020 at 7:49 AM Atsushi Nukariya ***@***.***> wrote: @MarcoGorelli <https://github.com/MarcoGorelli> @TomAugspurger <https://github.com/TomAugspurger> Thanks! I agree not to introduce many keywords. But I didn't intend to add more keyword arguments in this issue. This issue mentions the unclear documentation of **kwargs. I think adding a link of tabulate package <https://pypi.org/project/tabulate/> to this document is enough for the user. Or, it may be good to add an example which uses tabulate argument. The users can check what options they need to pass to **kwargs. What do you think of this idea? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#34568 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKAOIVM4NVNBEZCCLKEPNDRU6J33ANCNFSM4NSMRR5Q> .

[nuka137]

I noticed pandas.Series.to_markdown has same argument.
So, I also created PR for it (#34616 ).