From 9266a6524954a86c86155f0cc140bab7c883bca8 Mon Sep 17 00:00:00 2001 From: David Hoese Date: Wed, 28 May 2025 14:38:21 -0500 Subject: [PATCH 1/5] Remove old API doc modules --- docs/source/api/.gitkeep | 0 docs/source/api/pyresample.bilinear.rst | 21 --- docs/source/api/pyresample.bucket.rst | 10 -- docs/source/api/pyresample.ewa.rst | 29 ---- .../source/api/pyresample.future.geometry.rst | 29 ---- .../api/pyresample.future.resamplers.rst | 37 ----- docs/source/api/pyresample.future.rst | 19 --- docs/source/api/pyresample.gradient.rst | 10 -- docs/source/api/pyresample.rst | 146 ------------------ docs/source/api/pyresample.utils.rst | 53 ------- 10 files changed, 354 deletions(-) create mode 100644 docs/source/api/.gitkeep delete mode 100644 docs/source/api/pyresample.bilinear.rst delete mode 100644 docs/source/api/pyresample.bucket.rst delete mode 100644 docs/source/api/pyresample.ewa.rst delete mode 100644 docs/source/api/pyresample.future.geometry.rst delete mode 100644 docs/source/api/pyresample.future.resamplers.rst delete mode 100644 docs/source/api/pyresample.future.rst delete mode 100644 docs/source/api/pyresample.gradient.rst delete mode 100644 docs/source/api/pyresample.rst delete mode 100644 docs/source/api/pyresample.utils.rst diff --git a/docs/source/api/.gitkeep b/docs/source/api/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/source/api/pyresample.bilinear.rst b/docs/source/api/pyresample.bilinear.rst deleted file mode 100644 index 69da019a0..000000000 --- a/docs/source/api/pyresample.bilinear.rst +++ /dev/null @@ -1,21 +0,0 @@ -pyresample.bilinear package -=========================== - -Submodules ----------- - -pyresample.bilinear.xarr module -------------------------------- - -.. automodule:: pyresample.bilinear.xarr - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyresample.bilinear - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.bucket.rst b/docs/source/api/pyresample.bucket.rst deleted file mode 100644 index 401f7336a..000000000 --- a/docs/source/api/pyresample.bucket.rst +++ /dev/null @@ -1,10 +0,0 @@ -pyresample.bucket package -========================= - -Module contents ---------------- - -.. automodule:: pyresample.bucket - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.ewa.rst b/docs/source/api/pyresample.ewa.rst deleted file mode 100644 index bc5ae7c2f..000000000 --- a/docs/source/api/pyresample.ewa.rst +++ /dev/null @@ -1,29 +0,0 @@ -pyresample.ewa package -====================== - -Submodules ----------- - -pyresample.ewa.dask\_ewa module -------------------------------- - -.. automodule:: pyresample.ewa.dask_ewa - :members: - :undoc-members: - :show-inheritance: - -pyresample.ewa.ewa module -------------------------- - -.. automodule:: pyresample.ewa.ewa - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyresample.ewa - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.future.geometry.rst b/docs/source/api/pyresample.future.geometry.rst deleted file mode 100644 index 628ac464f..000000000 --- a/docs/source/api/pyresample.future.geometry.rst +++ /dev/null @@ -1,29 +0,0 @@ -pyresample.future.geometry package -================================== - -Submodules ----------- - -pyresample.future.geometry.area module --------------------------------------- - -.. automodule:: pyresample.future.geometry.area - :members: - :undoc-members: - :show-inheritance: - -pyresample.future.geometry.swath module ---------------------------------------- - -.. automodule:: pyresample.future.geometry.swath - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyresample.future.geometry - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.future.resamplers.rst b/docs/source/api/pyresample.future.resamplers.rst deleted file mode 100644 index 9a2c5fe92..000000000 --- a/docs/source/api/pyresample.future.resamplers.rst +++ /dev/null @@ -1,37 +0,0 @@ -pyresample.future.resamplers package -==================================== - -Submodules ----------- - -pyresample.future.resamplers.nearest module -------------------------------------------- - -.. automodule:: pyresample.future.resamplers.nearest - :members: - :undoc-members: - :show-inheritance: - -pyresample.future.resamplers.registry module --------------------------------------------- - -.. automodule:: pyresample.future.resamplers.registry - :members: - :undoc-members: - :show-inheritance: - -pyresample.future.resamplers.resampler module ---------------------------------------------- - -.. automodule:: pyresample.future.resamplers.resampler - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyresample.future.resamplers - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.future.rst b/docs/source/api/pyresample.future.rst deleted file mode 100644 index 1ff43f816..000000000 --- a/docs/source/api/pyresample.future.rst +++ /dev/null @@ -1,19 +0,0 @@ -pyresample.future package -========================= - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - pyresample.future.geometry - pyresample.future.resamplers - -Module contents ---------------- - -.. automodule:: pyresample.future - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.gradient.rst b/docs/source/api/pyresample.gradient.rst deleted file mode 100644 index 78e0567b0..000000000 --- a/docs/source/api/pyresample.gradient.rst +++ /dev/null @@ -1,10 +0,0 @@ -pyresample.gradient package -=========================== - -Module contents ---------------- - -.. automodule:: pyresample.gradient - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.rst b/docs/source/api/pyresample.rst deleted file mode 100644 index 6a3f925f4..000000000 --- a/docs/source/api/pyresample.rst +++ /dev/null @@ -1,146 +0,0 @@ -pyresample package -================== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - pyresample.bilinear - pyresample.bucket - pyresample.ewa - pyresample.future - pyresample.gradient - pyresample.utils - -Submodules ----------- - -pyresample.area\_config module ------------------------------- - -.. automodule:: pyresample.area_config - :members: - :undoc-members: - :show-inheritance: - -pyresample.boundary module --------------------------- - -.. automodule:: pyresample.boundary - :members: - :undoc-members: - :show-inheritance: - -pyresample.data\_reduce module ------------------------------- - -.. automodule:: pyresample.data_reduce - :members: - :undoc-members: - :show-inheritance: - -pyresample.geo\_filter module ------------------------------ - -.. automodule:: pyresample.geo_filter - :members: - :undoc-members: - :show-inheritance: - -pyresample.geometry module --------------------------- - -.. automodule:: pyresample.geometry - :members: - :undoc-members: - :show-inheritance: - -pyresample.grid module ----------------------- - -.. automodule:: pyresample.grid - :members: - :undoc-members: - :show-inheritance: - -pyresample.image module ------------------------ - -.. automodule:: pyresample.image - :members: - :undoc-members: - :show-inheritance: - -pyresample.kd\_tree module --------------------------- - -.. automodule:: pyresample.kd_tree - :members: - :undoc-members: - :show-inheritance: - -pyresample.plot module ----------------------- - -.. automodule:: pyresample.plot - :members: - :undoc-members: - :show-inheritance: - -pyresample.resampler module ---------------------------- - -.. automodule:: pyresample.resampler - :members: - :undoc-members: - :show-inheritance: - -pyresample.slicer module ------------------------- - -.. automodule:: pyresample.slicer - :members: - :undoc-members: - :show-inheritance: - -pyresample.spherical module ---------------------------- - -.. automodule:: pyresample.spherical - :members: - :undoc-members: - :show-inheritance: - -pyresample.spherical\_geometry module -------------------------------------- - -.. automodule:: pyresample.spherical_geometry - :members: - :undoc-members: - :show-inheritance: - -pyresample.spherical\_utils module ----------------------------------- - -.. automodule:: pyresample.spherical_utils - :members: - :undoc-members: - :show-inheritance: - -pyresample.version module -------------------------- - -.. automodule:: pyresample.version - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyresample - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/pyresample.utils.rst b/docs/source/api/pyresample.utils.rst deleted file mode 100644 index e132cd682..000000000 --- a/docs/source/api/pyresample.utils.rst +++ /dev/null @@ -1,53 +0,0 @@ -pyresample.utils package -======================== - -Submodules ----------- - -pyresample.utils.cartopy module -------------------------------- - -.. automodule:: pyresample.utils.cartopy - :members: - :undoc-members: - :show-inheritance: - -pyresample.utils.cf module --------------------------- - -.. automodule:: pyresample.utils.cf - :members: - :undoc-members: - :show-inheritance: - -pyresample.utils.errors module ------------------------------- - -.. automodule:: pyresample.utils.errors - :members: - :undoc-members: - :show-inheritance: - -pyresample.utils.proj4 module ------------------------------ - -.. automodule:: pyresample.utils.proj4 - :members: - :undoc-members: - :show-inheritance: - -pyresample.utils.rasterio module --------------------------------- - -.. automodule:: pyresample.utils.rasterio - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyresample.utils - :members: - :undoc-members: - :show-inheritance: From 8e2f0cb74c82f6c3b07a54423aeba6a1dc63fd19 Mon Sep 17 00:00:00 2001 From: David Hoese Date: Wed, 28 May 2025 21:01:19 -0500 Subject: [PATCH 2/5] Improve API documentation --- docs/README.md | 7 +---- docs/environment.yml | 1 + docs/source/conf.py | 38 +++++++++++++++++++++-- docs/source/reference.rst | 2 +- pyresample/_formatting_html.py | 4 +-- pyresample/area_config.py | 14 ++++++--- pyresample/bilinear/_base.py | 11 +++---- pyresample/bilinear/xarr.py | 11 +++---- pyresample/future/resamplers/resampler.py | 6 +--- pyresample/geometry.py | 8 ++--- 10 files changed, 61 insertions(+), 41 deletions(-) diff --git a/docs/README.md b/docs/README.md index d45695faf..c801db3e5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,9 +5,4 @@ by running: make html -The generated HTML documentation pages are available in `build/html`. If -Pyresample's API has changed (new functions, modules, classes, etc) then the -API documentation should be regenerated before running the above make -command. - - sphinx-apidoc -f -T -o source/api ../pyresample ../pyresample/test +The generated HTML documentation pages are available in `build/html`. diff --git a/docs/environment.yml b/docs/environment.yml index 9b9cc728b..e60c82d8a 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -18,3 +18,4 @@ dependencies: - pykdtree - sphinx_rtd_theme - sphinx-reredirects + - sphinx-autodoc-typehints diff --git a/docs/source/conf.py b/docs/source/conf.py index 7adb6d080..eeee149d2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -24,11 +24,14 @@ # -- General configuration ----------------------------------------------- +# sphinxcontrib.apidoc was added to sphinx in 8.2.0 as sphinx.etx.apidoc +needs_sphinx = "8.2.0" + # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx', - 'sphinx_reredirects', 'doi_role', + 'sphinx.ext.apidoc', 'sphinx_reredirects', 'doi_role', "sphinx_autodoc_typehints", ] # DocTest Settings @@ -52,6 +55,37 @@ Basemap = None ''' +# API docs +apidoc_modules = [ + { + "path": "../../pyresample", + "destination": "api/", + "exclude_patterns": [ + # Prefer to not document test modules. Most users will look at + # source code if needed and we want to avoid documentation builds + # suffering from import-time test data creation. We want to keep + # things contributors might be interested in like satpy.tests.utils. + "../../pyresample/test/test_*.py", + "../../pyresample/test/**/test_*.py", + ], + }, +] +apidoc_separate_modules = True +apidoc_include_private = True + +autodoc_mock_imports = ["hashlib._Hash"] +autodoc_type_aliases = { + "ArrayLike": "numpy.typing.ArrayLike", + "DTypeLike": "numpy.typing.DTypeLike", +} +autodoc_default_options = { + "special-members": "__init__, __reduce_ex__", +} +nitpick_ignore_regex: list[tuple[str, str]] = [] +autoclass_content = "both" # append class __init__ docstring to the class docstring + + + # Napoleon Settings (to support numpy style docs) napoleon_numpy_docstring = True napoleon_use_admonition_for_examples = True @@ -252,7 +286,7 @@ 'trollsift': ('https://trollsift.readthedocs.io/en/stable', None), 'trollimage': ('https://trollimage.readthedocs.io/en/stable', None), 'pyproj': ('https://pyproj4.github.io/pyproj/dev/', None), - 'proj': ('https://proj.org', None), + 'proj': ('https://proj.org/en/stable', None), 'satpy': ('https://satpy.readthedocs.io/en/stable', None), 'donfig': ('https://donfig.readthedocs.io/en/latest', None), } diff --git a/docs/source/reference.rst b/docs/source/reference.rst index f3827c82f..8b13a8083 100644 --- a/docs/source/reference.rst +++ b/docs/source/reference.rst @@ -11,6 +11,6 @@ of how to use this information see the :doc:`/howtos/index`. .. toctree:: :maxdepth: 1 - API + API roadmap dev_guide/index diff --git a/pyresample/_formatting_html.py b/pyresample/_formatting_html.py index 4203760ec..c56aa5c08 100644 --- a/pyresample/_formatting_html.py +++ b/pyresample/_formatting_html.py @@ -221,10 +221,8 @@ def swath_area_attrs_section(area: 'geom.SwathDefinition') -> str: # noqa F821 Returns: Html with collapsible section of swath attributes. - Todo: - - Improve resolution estimation from lat/lon arrays. Maybe use CoordinateDefinition.geocentric_resolution? - """ + # TODO: Improve resolution estimation from lat/lon arrays. Maybe use CoordinateDefinition.geocentric_resolution? if np.ndim(area.lons) == 1: area_name = "1D Swath" resolution_str = "NAxNA" diff --git a/pyresample/area_config.py b/pyresample/area_config.py index 4e1d4415c..d34028015 100644 --- a/pyresample/area_config.py +++ b/pyresample/area_config.py @@ -246,11 +246,15 @@ def _capture_subarguments(params: dict, arg_name: str, sub_arg_list: list[str]) """Capture :func:`~pyresample.utils.create_area_def` sub-arguments (i.e. units, height, dx, etc) from a yaml file. Example: - resolution: - dx: 11 - dy: 22 - units: meters - # returns DataArray((11, 22), attrs={'units': 'meters}) + Specify the units for the individual dx/dy values:: + + resolution: + dx: 11 + dy: 22 + units: meters + + would return the equivalent of ``DataArray((11, 22), attrs={'units': 'meters})``. + """ # Check if argument is in yaml. argument = params.get(arg_name) diff --git a/pyresample/bilinear/_base.py b/pyresample/bilinear/_base.py index 447428b1b..7de4543b8 100644 --- a/pyresample/bilinear/_base.py +++ b/pyresample/bilinear/_base.py @@ -25,8 +25,7 @@ """Code for resampling using bilinear algorithm for irregular grids. The algorithm is taken from - -http://www.ahinson.com/algorithms_general/Sections/InterpolationRegression/InterpolationIrregularBilinear.pdf +`here `__. """ @@ -424,8 +423,8 @@ def _ensure_array(val): def _calc_abc(corner_points, out_y, out_x): """Calculate coefficients for quadratic equation. - In this order of arguments used for _get_fractional_distances_irregular() and - _get_fractional_distances_uprights(). For _get_fractional_distances_uprights switch order of pt_2 and + In this order of arguments used for ``_get_fractional_distances_irregular()`` and + ``_get_fractional_distances_uprights()``. For ``_get_fractional_distances_uprights`` switch order of pt_2 and pt_3. """ @@ -451,9 +450,9 @@ def _calc_abc(corner_points, out_y, out_x): def _solve_another_fractional_distance(f__, y_corners, out_y): - """Solve parameter t__ from s__, or vice versa. + """Solve parameter ``t__`` from ``s__``, or vice versa. - For solving s__, switch order of y_2 and y_3. + For solving ``s__``, switch order of y_2 and y_3. """ y_1, y_2, y_3, y_4 = y_corners diff --git a/pyresample/bilinear/xarr.py b/pyresample/bilinear/xarr.py index 8cfbf0f0f..957062b4d 100644 --- a/pyresample/bilinear/xarr.py +++ b/pyresample/bilinear/xarr.py @@ -172,13 +172,10 @@ def from_delayed(delayeds, shp): slicer = get_slicer(data) - return from_delayed( - self._delayed_slice_data( - slicer, data, fill_value), shp) - - @delayed(nout=4) - def _delayed_slice_data(self, slicer, data, fill_value): - return slicer(data.values, self.slices_x, self.slices_y, self.mask_slices, fill_value) + delayed_slicer = delayed(slicer, pure=True, nout=4) + sliced_data = delayed_slicer(data, self.slices_x, self.slices_y, self.mask_slices, fill_value) + # TODO: Replace with single-chunk 'blockwise' call for better dask graph optimization + return from_delayed(sliced_data, shp) def _get_target_proj_vectors(self): try: diff --git a/pyresample/future/resamplers/resampler.py b/pyresample/future/resamplers/resampler.py index 65415f541..516da011f 100644 --- a/pyresample/future/resamplers/resampler.py +++ b/pyresample/future/resamplers/resampler.py @@ -31,14 +31,10 @@ from pyresample.geometry import AreaDefinition, CoordinateDefinition -if TYPE_CHECKING: - # defined in typeshed to hide private C-level type - from hashlib import _Hash - logger = logging.getLogger(__name__) -def hash_dict(the_dict: dict, existing_hash: Optional[_Hash] = None) -> _Hash: +def hash_dict(the_dict: dict, existing_hash: Optional[hashlib._Hash] = None) -> hashlib._Hash: """Calculate a hash for a dictionary and optionally update an existing hash.""" if existing_hash is None: existing_hash = hashlib.sha1() # nosec: B324 diff --git a/pyresample/geometry.py b/pyresample/geometry.py index 20a679a0e..311c83a09 100644 --- a/pyresample/geometry.py +++ b/pyresample/geometry.py @@ -71,10 +71,6 @@ logger = getLogger(__name__) -if TYPE_CHECKING: - # defined in typeshed to hide private C-level type - from hashlib import _Hash - class DimensionError(ValueError): """Wrap ValueError.""" @@ -133,7 +129,7 @@ def __hash__(self): self.hash = int(self.update_hash().hexdigest(), 16) return self.hash - def update_hash(self, existing_hash: Optional[_Hash] = None) -> _Hash: + def update_hash(self, existing_hash: Optional[hashlib._Hash] = None) -> hashlib._Hash: """Update the hash.""" if existing_hash is None: existing_hash = hashlib.sha1() # nosec: B324 @@ -2125,7 +2121,7 @@ def __ne__(self, other): """Test for equality.""" return not self.__eq__(other) - def update_hash(self, existing_hash: Optional[_Hash] = None) -> _Hash: + def update_hash(self, existing_hash: Optional[hashlib._Hash] = None) -> hashlib._Hash: """Update a hash, or return a new one if needed.""" if existing_hash is None: existing_hash = hashlib.sha1() # nosec: B324 From 79ef45b7d6cb739ac94dd0cfa7952310eb64eb72 Mon Sep 17 00:00:00 2001 From: David Hoese Date: Wed, 28 May 2025 21:16:42 -0500 Subject: [PATCH 3/5] Fix bilinear delayed usage --- pyresample/bilinear/xarr.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyresample/bilinear/xarr.py b/pyresample/bilinear/xarr.py index 957062b4d..78a5f93cb 100644 --- a/pyresample/bilinear/xarr.py +++ b/pyresample/bilinear/xarr.py @@ -173,9 +173,9 @@ def from_delayed(delayeds, shp): slicer = get_slicer(data) delayed_slicer = delayed(slicer, pure=True, nout=4) - sliced_data = delayed_slicer(data, self.slices_x, self.slices_y, self.mask_slices, fill_value) + sliced_dask_arr = delayed_slicer(data.data, self.slices_x, self.slices_y, self.mask_slices, fill_value) # TODO: Replace with single-chunk 'blockwise' call for better dask graph optimization - return from_delayed(sliced_data, shp) + return from_delayed(sliced_dask_arr, shp) def _get_target_proj_vectors(self): try: From 49f9ce430a73bd707ee9615dc351c99990f2ce46 Mon Sep 17 00:00:00 2001 From: David Hoese Date: Wed, 28 May 2025 21:23:13 -0500 Subject: [PATCH 4/5] Fix missing sphinx extension in CI --- continuous_integration/environment.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/continuous_integration/environment.yaml b/continuous_integration/environment.yaml index 4d98616dc..d1519feb4 100644 --- a/continuous_integration/environment.yaml +++ b/continuous_integration/environment.yaml @@ -26,4 +26,5 @@ dependencies: - pytest-cov - pytest-lazy-fixtures - sphinx-reredirects + - sphinx-autodoc-typehints - odc-geo From a3d1cdf4cbd11b7b48805e5425de591c42117012 Mon Sep 17 00:00:00 2001 From: David Hoese Date: Thu, 29 May 2025 08:35:39 -0500 Subject: [PATCH 5/5] Add autogenerated API .rst files to gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index ecf55361a..20714206f 100644 --- a/.gitignore +++ b/.gitignore @@ -65,3 +65,6 @@ pyresample/gradient/_gradient_search.c # don't include doctest files docs/doctest/.doctrees/* + +# don't include auto-generated API docs +docs/source/api/*.rst