Modify docstrings of wrapped functions. (#61)

List args and kwargs names that will be rewritten by cf_xarray if asked to and if possible.

Author: dcherian

cf_xarray/accessor.py

@@ -365,6 +365,38 @@ def _guess_bounds_dim(da):
     return result
 
 
+def _build_docstring(func):
+    """
+    Builds a nice docstring for wrapped functions, stating what key words
+    can be used for arguments.
+    """
+
+    # this list will need to be updated any time a new mapper is added
+    mapper_docstrings = {
+        _get_axis_coord: f"One or more of {(_AXIS_NAMES + _COORD_NAMES)!r}",
+        _get_axis_coord_single: f"One of {(_AXIS_NAMES + _COORD_NAMES)!r}",
+        _get_measure_variable: f"One of {_CELL_MEASURES!r}",
+    }
+
+    sig = inspect.signature(func)
+    string = ""
+    for k in set(sig.parameters.keys()) & set(_DEFAULT_KEY_MAPPERS):
+        mappers = _DEFAULT_KEY_MAPPERS.get(k, [])
+        docstring = "; ".join(
+            mapper_docstrings.get(mapper, "unknown. please open an issue.")
+            for mapper in mappers
+        )
+        string += f"\t\t{k}: {docstring} \n"
+
+    for param in sig.parameters:
+        if sig.parameters[param].kind is inspect.Parameter.VAR_KEYWORD:
+            string += f"\t\t{param}: {mapper_docstrings[_get_axis_coord]} \n\n"
+    return (
+        f"\n\tThe following arguments will be processed by cf_xarray: \n{string}"
+        "\n\t----\n\t"
+    )
+
+
 def _getattr(
     obj: Union[DataArray, Dataset],
     attr: str,
@@ -443,6 +475,8 @@ def wrapper(*args, **kwargs):
 
         return result
 
+    wrapper.__doc__ = _build_docstring(func) + wrapper.__doc__
+
     return wrapper
 
 

cf_xarray/tests/test_accessor.py

@@ -383,3 +383,8 @@ def test_add_bounds(obj, dims):
         assert name in added.coords
         assert added[dim].attrs["bounds"] == name
         assert_allclose(added[name].reset_coords(drop=True), expected[dim])
+
+
+def test_docstring():
+    assert "One of ('X'" in airds.cf.groupby.__doc__
+    assert "One or more of ('X'" in airds.cf.mean.__doc__