DOC: `DataFrame.stack()` should be updated for 3.0

[Dr-Irv]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.stack.html#pandas.DataFrame.stack

Documentation problem

The docs say that in 3.0 the API will change, and since it has changed, we should update the docs!

Suggested fix for documentation

remove dropna, sort and future_stack, since they have no effect any more??

[mroeschke]

Well users can still specify and use future_stack=False which use dropna and sort in pandas 3.0 though a Pandas4Warning will raise. We could update the docs to use the ... deprecated: 3.0 directive for these parameters to make it clearer

[Dr-Irv]

Well users can still specify and use future_stack=False which use dropna and sort in pandas 3.0 though a Pandas4Warning will raise. We could update the docs to use the ... deprecated: 3.0 directive for these parameters to make it clearer

yes, I think we should do that. For pandas-stubs, we are going to remove dropna and sort and future_stack, because we don't support deprecated params in the stubs. This encourages people to stop using them.

[anandvenugopal-tech]

Hi! I'd like to work on this documentation update.

I'll review the current behavior of DataFrame.stack() in pandas 3.0 and update the docstring and user guide section accordingly. Please let me know if there's anything specific I should consider before starting.