docs: improve docstrings configuration

mkdocs.yml

@@ -143,6 +143,12 @@ plugins:
         python:
           paths: [./ndsl]  # Adjust this path to where your Python modules are
           options:
+            # Filter out anything that starts with an underscore.
+            # Exceptions for `__init__(...)` and `__call__(...)` methods.
+            filters: ["!^_", "^__init__$", "^__call__$"]
+            group_by_category: true
+            members_order: source
+            show_if_no_docstring: true
             show_source: false
   - exclude:
       glob:

ndsl/comm/boundary.py

@@ -41,7 +41,7 @@ def send_slice(self, specification: QuantityHaloSpec) -> tuple[slice, ...]:
 
         Args:
             specification: data specifications for the halo. Including shape
-            and number of halo points.
+                and number of halo points.
 
         Returns:
             A tuple of slices (one per dimensions)
@@ -52,8 +52,8 @@ def recv_slice(self, specification: QuantityHaloSpec) -> tuple[slice, ...]:
         """Return the index slices which should be received at this boundary.
 
         Args:
-            quantity: quantity for which to return slices
-            n_points: the width of boundary to include
+            specification: data specifications for the halo. Including shape
+                and number of halo points.
 
         Returns:
             A tuple of slices (one per dimensions)

ndsl/comm/decomposition.py

@@ -12,11 +12,11 @@
 
 
 def determine_rank_is_compiling(rank: int, size: int) -> bool:
-    """Determines if a rank needs to be a compiling one
+    """Determines if a rank needs to be a compiling one.
 
     Args:
-        rank (int): current rank
-        size (int): size of the communicator
+        rank: current rank
+        size: size of the communicator
 
     Returns:
         bool: True if the rank is a compiling one
@@ -27,22 +27,22 @@ def determine_rank_is_compiling(rank: int, size: int) -> bool:
 def block_waiting_for_compilation(
     comm: MPI.Comm, compilation_config: CompilationConfig
 ) -> None:
-    """block moving on until an ok is received from the compiling rank
+    """Block moving on until an ok is received from the compiling rank.
 
     Args:
-        comm (MPI.Comm): communicator over which the ok is sent
-        stencil_config (CompilationConfig): holding communicator and rank information
+        comm: communicator over which the ok is sent
+        compilation_config: holding communicator and rank information
     """
     if comm and comm.Get_size() > 1:
         compiling_rank = compilation_config.compiling_equivalent
         _ = comm.recv(source=compiling_rank)
 
 
 def unblock_waiting_tiles(comm: MPI.Comm) -> None:
-    """sends a message to all the ranks waiting for compilation to finish
+    """Sends a message to all the ranks waiting for compilation to finish.
 
     Args:
-        comm (MPI.Comm): communicator over which the ok is sent
+        comm: communicator over which the ok is sent
     """
     rank = comm.Get_rank()
     size = comm.Get_size()
@@ -59,10 +59,10 @@ def check_cached_path_exists(cache_filepath: str) -> None:
 
 
 def build_cache_path(config: CompilationConfig) -> tuple[str, str]:
-    """generate the GT-Cache path from the config
+    """Generate the GT-Cache path from the config.
 
     Args:
-        config (CompilationConfig): stencil-config object at post-init state
+        config: stencil-config object at post-init state
 
     Returns:
         tuple[str, str]: path and individual rank string
@@ -80,7 +80,7 @@ def build_cache_path(config: CompilationConfig) -> tuple[str, str]:
 
 
 def set_distributed_caches(config: CompilationConfig) -> None:
-    """In Run mode, check required file then point current rank cache to source cache"""
+    """In Run mode, check required file then point current rank cache to source cache."""
 
     # Check that we have all the file we need to early out in case
     # of issues.

ndsl/comm/partitioner.py

@@ -69,7 +69,7 @@ def global_extent(self, rank_metadata: QuantityMetadata) -> tuple[int, ...]:
         """Return the shape of a full tile representation for the given dimensions.
 
         Args:
-            metadata: quantity metadata
+            rank_metadata: quantity metadata
 
         Returns:
             extent: shape of full tile representation
@@ -166,7 +166,7 @@ def global_extent(
         """Return the shape of a full tile representation for the given dimensions.
 
         Args:
-            metadata: quantity metadata
+            rank_metadata: quantity metadata
 
         Returns:
             extent: shape of full tile representation
@@ -608,7 +608,7 @@ def global_extent(self, rank_metadata: QuantityMetadata) -> tuple[int, ...]:
         """Return the shape of a full cube representation for the given dimensions.
 
         Args:
-            metadata: quantity metadata
+            rank_metadata: quantity metadata
 
         Returns:
             extent: shape of full cube representation
@@ -625,7 +625,7 @@ def subtile_extent(
         """Return the shape of a single rank representation for the given dimensions.
 
         Args:
-            global_metadata: quantity metadata.
+            cube_metadata: quantity metadata.
             rank: rank of the process.
 
         Returns:

ndsl/dsl/stencil.py

@@ -1002,7 +1002,6 @@ def from_origin_domain(
             func: stencil definition function
             origin: gt4py origin to use at call time
             domain: gt4py domain to use at call time
-            stencil_config: container for stencil configuration
             externals: compile-time external variables required by stencil
             skip_passes: compiler passes to skip when building stencil
         """

ndsl/grid/global_setup.py

@@ -16,10 +16,11 @@ def gnomonic_grid(grid_type: int, lon, lat, np):
     """
     Apply gnomonic grid to lon and lat arrays for all tiles. Tiles must then be rotated
     and mirrored to the correct orientations before use.
+
     This global mesh generation is the way the Fortran code initializes the lon/lat
     grids and is reproduced here for testing purposes.
 
-    args:
+    Args:
         grid_type: type of grid to apply
         lon: longitude array with dimensions [x, y]
         lat: latitude array with dimensions [x, y]

ndsl/grid/stretch_transformation.py

@@ -26,17 +26,16 @@ def direct_transform(
     centered on lon_target, lat_target.
 
     Args:
-        lon (in) in radians
-        lat (in) in radians
-        stretch_factor (in) stretch_factor (e.g. 3.0 means that the resolution
+        lon: longitude in radians
+        lat: latitude in radians
+        stretch_factor: stretch_factor (e.g. 3.0 means that the resolution
             on tile 6 becomes 3 times as fine)
-        lon_target (in) in degrees (from namelist)
-        lat_target (in) in degrees (from namelist)
+        lon_target: in degrees (from namelist)
+        lat_target: in degrees (from namelist)
         np: numpy or cupy module
 
     Returns:
-        lon_transform (out) in radians
-        lat_transform (out) in radians
+        (lon_transform, lat_transform): in radians
     """
 
     if isinstance(lon, Quantity):

ndsl/halo/updater.py

@@ -374,8 +374,8 @@ def __init__(
         """Initialize a CubedSphereCommunicator.
 
         Args:
-            comm: mpi4py.Comm object
-            partitioner: cubed sphere partitioner
+            comm: ndsl.Comm object
+            boundaries: ?
             force_cpu: Force all communication to go through central memory. Optional.
             timer: Time communication operations. Optional.
         """

ndsl/initialization/allocator.py

@@ -225,7 +225,6 @@ def get_quantity_halo_spec(
             dims: dimensionality of the data
             n_halo: number of halo points to update, defaults to self.n_halo
             dtype: data type of the data
-            backend: gt4py backend to use
         """
 
         # TEMPORARY: we do a nasty temporary allocation here to read in the hardware

ndsl/quantity/quantity.py

@@ -155,10 +155,10 @@ def from_data_array(
         allow_mismatch_float_precision: bool = False,
     ) -> Quantity:
         """
-        Initialize a Quantity from an xarray.DataArray.
+        Initialize a Quantity from an `xarray.DataArray`.
 
         Args:
-            data_array
+            data_array: `xarray.DataArray` to initialize from
             origin: first point in data within the computational domain
             extent: number of points along each axis within the computational domain
             allow_mismatch_float_precision: allow for precision that is

ndsl/restart/_legacy_restart.py

@@ -27,7 +27,7 @@ def open_restart(
     only_names: Iterable[str] | None = None,
     to_state: dict | None = None,
     tracer_properties: RestartProperties | None = None,
-):
+) -> dict:
     """Load restart files output by the Fortran model into a state dictionary.
 
     Args:

ndsl/stencils/basic_operations.py

@@ -66,7 +66,7 @@ def set_IJ_mask_value(mask_out: BoolFieldIJ, value: Bool) -> None:
     Sets every element of buffer to the value specified by value argument.
 
     Args:
-        buffer: output field
+        mask_out: output field
         value: value of Bool type
     """
     with computation(FORWARD), interval(0, 1):