Update regridding API naming convention

[jasonb5]

Description

• Closes [Doc]: Consider updating the listed APIs for horizontal regridding #501
• Adds deprecation notice for horizontal and vertical methods
• Adds vertical_xgcm method
• Moves documentation from *Regridder classes to RegridderAccessor methods.
• Updates horizontal_xesmf, horizontal_regrid2, and vertical_xgcm docstrings.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

If applicable:

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass with my changes (locally and CI/CD build)
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have noted that this is a breaking change for a major release (fix or feature that would cause existing functionality to not work as expected)

[codecov-commenter]

Codecov Report

Patch coverage: 80.00% and project coverage change: -0.14 ⚠️

Comparison is base (870b334) 100.00% compared to head (d9b19af) 99.86%.

❗ Current head d9b19af differs from pull request most recent head b10940a. Consider uploading reports for the commit b10940a to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #510      +/-   ##
===========================================
- Coverage   100.00%   99.86%   -0.14%     
===========================================
  Files           15       15              
  Lines         1562     1524      -38     
===========================================
- Hits          1562     1522      -40     
- Misses           0        2       +2     

Impacted Files	Coverage Δ
xcdat/regridder/xesmf.py	100.00% <ø> (ø)
xcdat/regridder/xgcm.py	100.00% <ø> (ø)
xcdat/regridder/accessor.py	96.96% <77.77%> (-3.04%)	⬇️
xcdat/regridder/regrid2.py	100.00% <100.00%> (ø)

... and 3 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[tomvothecoder]

Thanks for this PR. Feel free to assign reviewers whenever PRs are ready to get things rolling.

I'll do an initial review.

[tomvothecoder]

I don't think this PR is ready for review so I'll hold off on reviewing

[jasonb5]

@tomvothecoder This is ready for review.
@chengzhuzhang @lee1043 @pochedls Feel free to invite other reviewers. I'm hoping these changes will improve the visibility of the regridder documentation. Let me know if anything is still unclear and can be improved, thank you!

[jasonb5]

Setting this as a draft as it depends on #507. I'll need to make some additional updates to documentation after it's merged.

[tomvothecoder]

Hey @jasonb5, let's push this PR back to give more time for discussion since it is not a crucial for v0.6.0. @chengzhuzhang and @lee1043 are in favor of keeping the .horizontal() wrapper that encapsulates all of the tools through the tool arg.

I tried to summarize our discussion at the meeting below:

Why this PR was kickstarted (#501)

• Too many regridding APIs for the same functionality -- can be confusing for new users (maybe we can remove the individual accessor methods from the docs?)
  • Wrapper method: https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal.html
  • Individual method: https://xcdat.readthedocs.io/en/stable/generated/xarray.Dataset.regridder.horizontal_xesmf.html
  • Underlying class: https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.xesmf.XESMFRegridder.html
• For the **options arg, users need to go to the individual API documentations for options (cumbersome to navigate) -- combining them under .horizontal will make the docstring too long
  • https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.regrid2.Regrid2Regridder.html#xcdat.regridder.regrid2.Regrid2Regridder
  • https://xcdat.readthedocs.io/en/stable/generated/xcdat.regridder.xesmf.XESMFRegridder.html#xcdat.regridder.xesmf.XESMFRegridder
• There is minimal overlap in with **options between regrid2 and xesmf
• The number of lines for the API is more with the wrapper
  • ds.regridder.horizontal(...tool="xesmf") vs. ds.regridder.horizontal_xesmf()

Reasons to keep .horizontal() wrapper

• If users are really interested in the regridder options, they will read the docstring and go to the individual API pages
• It gives more flexibility in usage and testing since the tool argument just needs to be swapped vs. importing individual APIs
• xesmf is a widely used tool and should be the default option
  • regrid2 is mainly for CDAT users who need to reproduce the same results using xCDAT

[tomvothecoder]

I came across this style of reusable docstrings in xarray. It might be useful if we want to consolidate and reuse docstrings:

https://github.com/pydata/xarray/blob/main/xarray/core/weighted.py#L25-L52
https://github.com/pydata/xarray/blob/1146c5a3cdb15d402e95153c3ea68826b158d953/xarray/core/weighted.py#L546-L569

[jasonb5]

Closing as we've decided to stick with generic horizontal and vertical methods. PR #535 addresses the documentation changes in this PR.