Use NumPy-style for docstrings

Author: MalloryWittwer

src/imaging_server_kit/__init__.py

@@ -47,19 +47,25 @@
 
 
 def convert(stack: Stack, to: str = "stack") -> Union[Stack, "napari.Viewer"]:
-    """
-    Convert a result object into a different representation.
+    """Convert a stack into another representation.
 
     Parameters
     ----------
-    stack : The result object to convert.
-    to : The target representation to convert to. Supported values: ["stack", "napari"]
+    stack : Stack
+        The stack to convert.
+    to : {"stack", "napari"}, default="stack"
+        The target representation.
 
     Returns
     -------
-    The converted result object.
-    - If `to == "stack"`, a Stack() object containing copies of the input layers.
-    - If `to == "napari"` the napari.Viewer associated with the converted stack.
+    Stack or napari.Viewer
+        With `to="stack"`, a new stack with the same layers. With `to="napari"`, a new
+        Napari viewer displaying the layers (requires the `napari` extra).
+
+    Raises
+    ------
+    ValueError
+        If `to` is not supported.
     """
     supported = ["stack", "napari"]
     if not to in supported:
@@ -96,7 +102,21 @@ def run(
     domain: Optional[Domain] = None,
     **algo_params,
 ) -> Union[Stack, "napari.Viewer"]:  # type: ignore
-    """Allows the syntax `sk.run(...)` instead of runner.run(...)."""
+    """Run an algorithm. Equivalent to `runner.run(...)`.
+
+    See [`AlgorithmRunner.run`][imaging_server_kit.AlgorithmRunner.run] for the
+    description of the parameters.
+
+    Parameters
+    ----------
+    runner : AlgorithmRunner
+        An algorithm, an algorithm collection, or a client.
+
+    Returns
+    -------
+    Stack or napari.Viewer
+        The results, as returned by `runner.run(...)`.
+    """
     return runner.run(
         *args,
         algorithm=algorithm,
@@ -112,5 +132,13 @@ def run(
 
 
 def info(runner: AlgorithmRunner, algorithm: Optional[str] = None):
-    """Allow the syntax `sk.info(...)` instead of runner.info(...)."""
+    """Open the documentation page of an algorithm. Equivalent to `runner.info(...)`.
+
+    Parameters
+    ----------
+    runner : AlgorithmRunner
+        An algorithm, an algorithm collection, or a client.
+    algorithm : str, optional
+        Name of the algorithm (only needed with collections and clients).
+    """
     return runner.info(algorithm=algorithm)

src/imaging_server_kit/core/algorithm.py

@@ -204,46 +204,54 @@ def _yields_then_return(gen: Generator) -> Generator[Any, None, None]:
 
 
 class Algorithm(AlgorithmRunner, Generic[P]):
-    """An algorithm built by wrapping a Python function. Usually created via the `@sk.algorithm(...)` decorator rather than instantiated directly.
+    """An algorithm built by wrapping a Python function.
+
+    Algorithms are usually created with the `@sk.algorithm` decorator rather than
+    instantiated directly. They can still be called like the wrapped function, and
+    also implement the shared [`AlgorithmRunner`][imaging_server_kit.AlgorithmRunner]
+    interface (`run()`, `get_sample()`, `info()`, etc.).
 
     Parameters
     ----------
-    run_algorithm_func: The Python function to convert.
-    parameters: A dictionary of annotated parameters.
-    name: A name for the algorithm (doesn't accept spaces and special characters).
-    description: A short description to display on the algorithm doc page. Defaults to the docstring of the Python function.
-    tags: A list of tags (arbitrary).
-    project_url: A link to a related, or the original project (gets displayed on the algo doc page).
-    metadata_file: A path to a metadata.yaml file with algorithm metadata.
-    samples: A list of sample parameters for the algorithm, each represented as a dictionary mapping parameter_name to example_value. Sample images can be a Numpy array, a URL, or a local path to a file readable by `skimage.io.imread`.
-    tileable: Whether to allow running the algorithm tile-by-tile.
-
-    Notes
-    ----------
-    - Algorithms can be converted to FastAPI servers or PyQt widgets for Napari or QuPath.
-    - Algorithms are associated with a Pydantic Schema that can be used to validate input parameters.
-    - Algorithms can be run tile-by-tile (in most cases).
-    - Algorithms can be run on a subset of the spatial domain defined by their inputs.
-    - Algorithms can provide `samples` (example inputs).
-    - Algorithm metadata can populate an `info` page.
+    run_algorithm_func : callable
+        The Python function to convert.
+    parameters : dict, optional
+        Parameter annotations, mapping parameter names to data layers (e.g.
+        `{"sigma": sk.Float(min=0, default=1.0)}`). Parameters that are not annotated
+        are resolved from type hints, default values, or variable names.
+    name : str, optional
+        A name for the algorithm. Defaults to the name of the function.
+    description : str, optional
+        A short description, displayed on the algorithm documentation page. Defaults
+        to the docstring of the function.
+    tags : list of str, optional
+        A list of tags (arbitrary), displayed on the algorithm documentation page.
+    project_url : str, optional
+        A link to a related project, or to the original project, displayed on the
+        algorithm documentation page.
+    metadata_file : str, default="metadata.yaml"
+        A path to a YAML file with algorithm metadata.
+    samples : list of dict, optional
+        Samples for the algorithm. Each sample is a dictionary mapping parameter
+        names to example values. Sample images can be NumPy arrays, URLs, or paths to
+        local files readable by `skimage.io.imread`.
+    tileable : bool, default=False
+        Whether the algorithm can be run tile-by-tile.
 
     Attributes
     ----------
-    name: A name for the algorithm.
-    parameters_model: A JSON schema representation of algorithm parameters.
-    samples: A list of sample parameters, mapping parameter names to parameter values.
-    algo_info: A dictionary of metadata about the algorithm.
-    algorithms: A list containing the algorithm's name.
-
-    Methods
-    ----------
-    run(): Execute the algorithm with a set of parameters.
-        Set `tiled=True` for tiled inference.
-        Raises a ValidationError when parameters are invalidated.
-    get_n_samples(): Get the number of samples available.
-    get_sample(): Get a sample by index.
-    info(): Access algorithm documentation.
-    get_parameters(): Get the algorithm parameters schema.
+    name : str
+        The name of the algorithm.
+    parameters_model : pydantic.BaseModel
+        A Pydantic model used to validate the algorithm parameters.
+    samples : list of dict
+        The samples of the algorithm.
+    algo_info : dict
+        Metadata about the algorithm.
+    algorithms : list of str
+        A list containing the name of the algorithm.
+    tileable : bool
+        Whether the algorithm can be run tile-by-tile.
     """
 
     def __init__(
@@ -489,23 +497,49 @@ def algorithm(
     samples: Optional[List[Dict[str, Any]]] = None,
     tileable: bool = False,
 ) -> Union[Algorithm[P], Callable[[Callable[P, Any]], Algorithm[P]]]:
-    """Wrap a Python function as an algorithm (sk.Algorithm). Typically used as the `@sk.algorithm(...)` decorator.
+    """Convert a Python function into an algorithm.
+
+    Typically used as a decorator, with or without arguments: `@sk.algorithm` or
+    `@sk.algorithm(...)`.
 
     Parameters
     ----------
-    func : The Python function to convert.
-    parameters : A dictionary of annotated parameters.
-    name: A name for the algorithm (doesn't accept spaces and special characters).
-    description: A short description to display on the algorithm doc page. Defaults to the docstring of the Python function.
-    tags: A list of tags (arbitrary).
-    project_url: A link to a related, or the original project (gets displayed on the algo doc page).
-    metadata_file: A path to a metadata.yaml file with algorithm metadata.
-    samples: A list of sample parameters for the algorithm, each represented as a dictionary mapping parameter_name to example_value. Sample images can be a Numpy array, a URL, or a local path to a file readable by `skimag.io.imread`.
-    tileable: Whether to allow running the algorithm tile-by-tile.
+    func : callable, optional
+        The Python function to convert. Passed implicitly when used as a decorator.
+    parameters : dict, optional
+        Parameter annotations, mapping parameter names to data layers (e.g.
+        `{"sigma": sk.Float(min=0, default=1.0)}`). Parameters that are not annotated
+        are resolved from type hints, default values, or variable names.
+    name : str, optional
+        A name for the algorithm. Defaults to the name of the function.
+    description : str, optional
+        A short description, displayed on the algorithm documentation page. Defaults
+        to the docstring of the function.
+    tags : list of str, optional
+        A list of tags (arbitrary), displayed on the algorithm documentation page.
+    project_url : str, optional
+        A link to a related project, or to the original project, displayed on the
+        algorithm documentation page.
+    metadata_file : str, default="metadata.yaml"
+        A path to a YAML file with algorithm metadata.
+    samples : list of dict, optional
+        Samples for the algorithm. Each sample is a dictionary mapping parameter
+        names to example values. Sample images can be NumPy arrays, URLs, or paths to
+        local files readable by `skimage.io.imread`.
+    tileable : bool, default=False
+        Whether the algorithm can be run tile-by-tile.
 
     Returns
     -------
-    An algorithm instance (sk.Algorithm).
+    Algorithm
+        The algorithm. When called with keyword arguments only, a decorator
+        returning the algorithm.
+
+    Examples
+    --------
+    >>> @sk.algorithm(parameters={"threshold": sk.Integer(min=0, max=255, default=128)})
+    ... def threshold_algo(image, threshold):
+    ...     return sk.Mask(image > threshold)
     """
 
     def _decorate(run_algorithm_func: Callable[P, Any]) -> Algorithm[P]:

src/imaging_server_kit/core/domain.py

@@ -5,25 +5,35 @@
 
 
 class Domain:
-    """A nD-domain defined by a size and position in global pixel space. Used to represent tile extents, and to restrict an algorithm's computation to a specific region.
+    """An n-D box defined by a size and a position in global pixel coordinates.
+
+    Domains represent regions of interest and tile extents, and are used to restrict
+    the computation of an algorithm to a region.
 
     Parameters
     ----------
-    size: Size of the domain in pixels, one value per dimension.
-    position: Position of the domain's top-left corner in global pixel space. Defaults to the origin (all zeros) if only `size` is provided.
+    size : tuple, optional
+        Size of the domain in pixels, one value per dimension.
+    position : tuple, optional
+        Position of the lower corner of the domain (top-left in 2D), in global pixel
+        coordinates. Defaults to the origin if only `size` is provided.
 
     Attributes
     ----------
-    size: Size of the domain in pixels.
-    coords_min: The position of the top-left corner of the domain.
-    coords_max: The position of the bottom-right corner of the domain.
-    ndim: Number of dimensions.
-
-    Methods
-    ----------
-    serialize(): Convert the domain to a dictionary format.
-    copy(): Copy the domain.
-    merge(): Merge another domain.
+    size : tuple
+        Size of the domain in pixels.
+    coords_min : tuple
+        Lower corner of the domain (top-left in 2D).
+    coords_max : tuple
+        Upper corner of the domain (bottom-right in 2D).
+    ndim : int
+        Number of dimensions.
+
+    Examples
+    --------
+    >>> roi = sk.Domain(position=(20, 30), size=(60, 80))
+    >>> roi.coords_max
+    (80.0, 110.0)
     """
 
     def __init__(

src/imaging_server_kit/core/multialgo.py

@@ -7,22 +7,27 @@
 
 
 class MultiAlgorithm(AlgorithmRunner):
-    """A collection of algorithms exposed under a single interface, with the target algorithm selected by name at call time. Usually created via the `sk.combine()` function rather than instantiated directly.
+    """A collection of algorithms exposed under a single interface.
+
+    Collections are usually created with `sk.combine()` rather than instantiated
+    directly. They implement the shared
+    [`AlgorithmRunner`][imaging_server_kit.AlgorithmRunner] interface, where methods
+    take an `algorithm` argument to select an algorithm by name.
 
     Parameters
     ----------
-    algorithms: A list of algorithm instances in the collection.
-    name: A name for the algorithm collection.
+    algorithms : list of Algorithm
+        The algorithms in the collection. If several algorithms have the same name,
+        only the last one is kept.
+    name : str, default="algorithms"
+        A name for the collection.
 
     Attributes
     ----------
-    algorithms_dict: A dictionary mapping algorithm names to instances in the collection.
-    algorithms: A list of algorithm names in the collection.
-
-    Methods
-    ----------
-    This class implements the same methods as the Algorithm class (via AlgorithmRunner),
-    but methods take an extra argument `algorithm` to identify the algorithm to use.
+    algorithms_dict : dict
+        A dictionary mapping algorithm names to algorithms.
+    algorithms : list of str
+        The names of the algorithms in the collection.
     """
 
     def __init__(self, algorithms: List[Algorithm], name: str = "algorithms"):
@@ -86,17 +91,23 @@ def _stream(self, algorithm: str, params_stack: Stack):
 
 
 def combine(algorithms: List[Algorithm], name: str = "algorithms") -> MultiAlgorithm:
-    """
-    Combine multiple algorithms, or plain Python functions, into a single algorithm collection.
+    """Combine algorithms, or plain Python functions, into a collection.
 
     Parameters
     ----------
-    algorithms : A list of algorithm objects, or python functions. Python functions are converted to algorithms directly.
-    name : The name of the algorithm collection.
+    algorithms : list of Algorithm or callable
+        The algorithms to combine. Plain Python functions are converted to algorithms.
+    name : str, default="algorithms"
+        A name for the collection.
 
     Returns
     -------
-    An algorithm collection (sk.MultiAlgorithm).
+    MultiAlgorithm
+        The algorithm collection.
+
+    Examples
+    --------
+    >>> multi_algo = sk.combine([threshold_algo, gaussian_algo], name="my-algorithms")
     """
     parsed_algorithms = []
     for algorithm in algorithms: