Update isku.extract_regions docs

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Minor improvements to README, CONTRIBUTING docs, developer experience. ([@brews](https://github.com/brews), [PR#42](https://github.com/ClimateImpactLab/isku/pull/42))
 - Mention "segment weights" in `GridWeightingRegions` API docs. ([@brews](https://github.com/brews), [PR#60](https://github.com/ClimateImpactLab/isku/pull/60))
+- Improve documentation for `isku.extract_regions`. ([@brews](https://github.com/brews), [PR#73](https://github.com/ClimateImpactLab/isku/pull/73))
 
 
 ## [0.3.0] - 2026-05-15

src/isku/extract.py

@@ -135,12 +135,30 @@ def extract_regions(
     ds: xr.Dataset, *, template: ExtractionTemplate, regions: RegionExtractor
 ) -> xr.Dataset:
     """
-    Use transformations in 'template' to extract 'regions' from gridded dataset, 'ds', returning a regionalized dataset
-
-    This function specifically does not just regionalize through zonal aggregation. It uses 'template' to apply pre/post regionalization transformations to create new datasets and variables.
+    Regionalize a gridded dataset with a template of pre- and post-extraction transformations
+
+    Parameters
+    ----------
+    ds :
+        A gridded dataset with variables to regionalize and transform.
+    template :
+        A template describing pre- and post-regionalization trasformations to create the output regionalized data.
+    regions :
+        Regions to extract from the gridded dataset.
+
+    Returns
+    -------
+    out :
+        A regionalized dataset.
+
+    Notes
+    -----
+    This function is especially concerned with applying a transformation step before regions are extracted, and applying a transformation after extraction. To extract regions _without_ the surrounding transformations, use the [extract_regions][isku.RegionExtractor.extract_regions] method on whatever was passed for the `regions` argument.
 
     See Also
     --------
-    build_extraction_template: Quickly build extraction workflow from functions for regionalization.
+    [build_extraction_template][isku.build_extraction_template]: Quickly build extraction templates from functions.
+
+    [GridWeightingRegions][isku.GridWeightingRegions]: An example of a [RegionExtractor][isku.RegionExtractor] that can be used for the `regions` argument.
     """
     return template.post_extract(regions.extract_regions(template.pre_extract(ds)))

zensical.toml

@@ -378,7 +378,7 @@ docstring_style = "numpy"
 separate_signature = true
 # preload_modules = ["xarray"]  # Xarray does not work with intersphinx inventories...? (https://github.com/pydata/xarray/issues/4279)
 members_order = "source"
-parameter_headings = true
+parameter_headings = false
 type_parameter_headings = true
 docstring_section_style = "list"
 show_object_full_path = false