Adding sample datasets to be used in the documentation

[datapythonista]

• closes DOC: develop a set of standard example DataFrames for use in docstring examples #19710
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[jreback]

I thought we had an issue about this already, IIRC @mrocklin either made it or commented (was for a slightly different purpose though).

[jreback]

We already have lots of data constructors in pandas.util.testing, though these are 'nicer' ones. These would need testing (e.g. do they run), and can be de-privatized (no leading _).

[jorisvandenbossche]

I thought we had an issue about this already, IIRC @mrocklin either made it or commented (was for a slightly different purpose though).

I don't know if there is an older issue, but this is related to what is recently discussed in #19710 as @datapythonista linked to.

We already have lots of data constructors in pandas.util.testing, though these are 'nicer' ones.

Indeed, I don't think the ones in util.testing are suitable for this, as the exact purpose of those are to be 'nicer' relate-able small dataframes.

[datapythonista]

Any more thoughts on this? Knowing which data to use for the examples in the docstrings is the main blocker for the sprint. Any feedback on how you think we can improve this first draft is highly appreciated. Thanks!

[jorisvandenbossche]

This needs to be imported in some __init__ files, as otherwise you cannnot do pd.io.samples. .... Or what would be the intended use in the docs?

[jreback]

these need to be de-privatized (no leading _)

[jreback]

these need tests

[datapythonista]

For what has been discussed in #19710, seems like it probably makes more sense to simply have some ideas on data to be used, but use custom datasets as simple and illustrative as possible depending on each case. So, closing this.