ENH: Implement PDEP-17
- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
- [ ] [Tests added and passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#writing-tests) if fixing a bug or adding a new feature
- [ ] All [code checks passed](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#pre-commit).
- [ ] Added [type annotations](https://pandas.pydata.org/pandas-docs/dev/development/contributing_codebase.html#type-hints) to new arguments/methods/functions.
- [ ] Added an entry in the latest `doc/source/whatsnew/vX.X.X.rst` file if fixing a bug or adding a new feature.

Continuation of #58169

Still needs tests and some cleanup with the docs and decorator arguments, but I'd like to get a first look.

cc @Dr-Irv @Aloqeely 
Seems like the label `PDEP` can only be used for the PDEP themselves. Otherwise building the website fails, as it expects the PR to be a PDEP that needs to be rendered in the roadmap. @Dr-Irv - Thanks for the review! I'm negative on the name `PandasWarning` for a class that has to do with deprecations. pandas emits many warnings, not all are about deprecations. > @Dr-Irv - Thanks for the review! I'm negative on the name `PandasWarning` for a class that has to do with deprecations. pandas emits many warnings, not all are about deprecations.

Maybe a different name would solve that?  Maybe `PandasDeprecationOrFutureWarning` or something like that.
 > Maybe a different name would solve that? Maybe `PandasDeprecationOrFutureWarning` or something like that.

Currently using `PandasChangeWarning`, which has my personal preference so far. Always open to other options or opinions! > I think there should be separate docs about the deprecation policy and these classes, aside from what is in the whatsnew document.

I've added some implementation details to PDEP-17, and more details to the whatsnew. If you'd like to see this documented somewhere else, can you detail where. @bashtage - pandas_datareader is using the `deprecate_kwarg` decorator. I'm modifying it here, is this an issue? @mroeschke - this should be ready. > Can you think of a linting rule that could remind us to use these new warning classes instead of FutureWarning and DeprecationWarning?

I think we can raise in `tm.assert_produces_warning` whenever a straight Future/Deprecation/PendingDeprecationWarning is passed. However we cannot do this at the moment as there are a bunch of FutureWarnings that need to be enforced for pandas 3.0.

My suggestion would be to move forward here, enforce pandas 3.0 deprecations, and revisit adding such logic to `tm.assert_produces_warning`. I don't doubt there will be adding warnings that need to be converted at that point, happy to take up that work. I can only build the docs in this PR if I specify `--num-jobs=1` and cannot reproduce this locally. @mroeschke - okay to merge? Thanks @rhshadrach 