From a18e4d17b4685645377ea8be65556418d012cf39 Mon Sep 17 00:00:00 2001 From: Roman Cattaneo <1116746+romanc@users.noreply.github.com> Date: Wed, 28 Jan 2026 12:24:48 +0100 Subject: [PATCH 1/3] docs: imporve docstrings configuration This PR improves the auto-generated docs from docstrings. The filter, makes sure we hide all methods/constants/attribues starting with at least one underscore. It adds an exception for `__init__(...)` methods. `show_if_no_docstrings` tells the system to show all methods/constants/attributes even if they don't have a docstring attached. This is especially useful for things like enums, where the enum name can be sufficient. `members_order` and `group_by_category` relate to how entries on pages are sorted/grouped. The default is "ungrouped" and in alphabetical order. Imo that leads to weirdly looking pages. This PR suggest to keep the order as in source code and group by category (e.g. constants, classes, ...) --- mkdocs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index aac85b0d..c81dc6aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -143,6 +143,12 @@ plugins: python: paths: [./ndsl] # Adjust this path to where your Python modules are options: + filters: + - "!^_" + - "^__init__$" + group_by_category: true + members_order: source + show_if_no_docstring: true show_source: false - exclude: glob: From 534293d4e05c1016b298599c28586b4d65c29d14 Mon Sep 17 00:00:00 2001 From: Roman Cattaneo <1116746+romanc@users.noreply.github.com> Date: Wed, 28 Jan 2026 15:08:24 +0100 Subject: [PATCH 2/3] Add exception for `__call__(...)` dunder methods --- mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index c81dc6aa..0e5738f1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -143,9 +143,9 @@ plugins: python: paths: [./ndsl] # Adjust this path to where your Python modules are options: - filters: - - "!^_" - - "^__init__$" + # 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 From b44c4eeb5c77b88796d6f6e437693f1f38b438fa Mon Sep 17 00:00:00 2001 From: Roman Cattaneo <1116746+romanc@users.noreply.github.com> Date: Wed, 28 Jan 2026 15:21:26 +0100 Subject: [PATCH 3/3] Minor docstring changes to cut down on warnings emitted --- ndsl/comm/boundary.py | 6 +++--- ndsl/comm/decomposition.py | 22 +++++++++++----------- ndsl/comm/partitioner.py | 8 ++++---- ndsl/dsl/stencil.py | 1 - ndsl/grid/global_setup.py | 3 ++- ndsl/grid/stretch_transformation.py | 13 ++++++------- ndsl/halo/updater.py | 4 ++-- ndsl/initialization/allocator.py | 1 - ndsl/quantity/quantity.py | 4 ++-- ndsl/restart/_legacy_restart.py | 2 +- ndsl/stencils/basic_operations.py | 2 +- 11 files changed, 32 insertions(+), 34 deletions(-) diff --git a/ndsl/comm/boundary.py b/ndsl/comm/boundary.py index e018b8f0..fba11552 100644 --- a/ndsl/comm/boundary.py +++ b/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) diff --git a/ndsl/comm/decomposition.py b/ndsl/comm/decomposition.py index 89781e0e..2f2dc967 100644 --- a/ndsl/comm/decomposition.py +++ b/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,11 +27,11 @@ 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 @@ -39,10 +39,10 @@ def block_waiting_for_compilation( 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. diff --git a/ndsl/comm/partitioner.py b/ndsl/comm/partitioner.py index a5c907df..ea154294 100644 --- a/ndsl/comm/partitioner.py +++ b/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: diff --git a/ndsl/dsl/stencil.py b/ndsl/dsl/stencil.py index e77e02b0..7cf27a64 100644 --- a/ndsl/dsl/stencil.py +++ b/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 """ diff --git a/ndsl/grid/global_setup.py b/ndsl/grid/global_setup.py index 1f8f68dd..55e72964 100644 --- a/ndsl/grid/global_setup.py +++ b/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] diff --git a/ndsl/grid/stretch_transformation.py b/ndsl/grid/stretch_transformation.py index 65b0f1a7..4c5387b7 100644 --- a/ndsl/grid/stretch_transformation.py +++ b/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): diff --git a/ndsl/halo/updater.py b/ndsl/halo/updater.py index 95d96313..1cd19499 100644 --- a/ndsl/halo/updater.py +++ b/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. """ diff --git a/ndsl/initialization/allocator.py b/ndsl/initialization/allocator.py index 6b01d449..fffa370a 100644 --- a/ndsl/initialization/allocator.py +++ b/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 diff --git a/ndsl/quantity/quantity.py b/ndsl/quantity/quantity.py index b0cdb3f3..a65c1acd 100644 --- a/ndsl/quantity/quantity.py +++ b/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 diff --git a/ndsl/restart/_legacy_restart.py b/ndsl/restart/_legacy_restart.py index 9cf577fe..1d03327b 100644 --- a/ndsl/restart/_legacy_restart.py +++ b/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: diff --git a/ndsl/stencils/basic_operations.py b/ndsl/stencils/basic_operations.py index fc6b2c0d..f0a6b994 100644 --- a/ndsl/stencils/basic_operations.py +++ b/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):