Improve API documentation

Author: djhoese

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`.

docs/environment.yml

@@ -18,3 +18,4 @@ dependencies:
   - pykdtree
   - sphinx_rtd_theme
   - sphinx-reredirects
+  - sphinx-autodoc-typehints

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),
 }

docs/source/reference.rst

@@ -11,6 +11,6 @@ of how to use this information see the :doc:`/howtos/index`.
 .. toctree::
    :maxdepth: 1
 
-   API <api/pyresample>
+   API <api/modules>
    roadmap
    dev_guide/index

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"

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)

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 <http://www.ahinson.com/algorithms_general/Sections/InterpolationRegression/InterpolationIrregularBilinear.pdf>`__.
 
 """
 
@@ -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
 

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:

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

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