DOC/DEPR: pandas.to_pickle

[twoertwein]

to_pickle is exported in the pandas.__init__ but not documented to be accessible from there (non of the other to_<IO> functions are exported in pandas.__init__).

Should to_pickle be removed/deprecated from pandas.__init__ or should it be documented?

xref pandas-dev/pandas-stubs#206 @Dr-Irv @bashtage

[bashtage]

It wasn't clear whether this was an accident or intentional. Since it was in the top level we decided to keep it in stubs. If this isn't really part of the API, it would probably need to be deprecated even though it isn't in the docs.

[mroeschke]

Looks like we're using and indirectly testing this in the testing utility round_trip_pickle, but it looks to be some functionality on top of pickle.dump

+1 to deprecate pd.to_pickle if it can be easily replaced in round_trip_pickle