Improve docs (#72)

Author: flying-sheep

docs/conf.py

@@ -36,6 +36,8 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    # "scanpydoc.definition_list_typed_field",
     "scanpydoc.elegant_typehints",
     "sphinx_autofixture",
 ]
@@ -59,6 +61,7 @@
     cupy=("https://docs.cupy.dev/en/stable/", None),
     dask=("https://docs.dask.org/en/stable/", None),
     h5py=("https://docs.h5py.org/en/stable/", None),
+    numba=("https://numba.readthedocs.io/en/stable/", None),
     numpy=("https://numpy.org/doc/stable/", None),
     python=("https://docs.python.org/3", None),
     scipy=("https://docs.scipy.org/doc/scipy/", None),

docs/conv.rst

@@ -0,0 +1,11 @@
+``fast_array_utils.conv``
+=========================
+
+.. automodule:: fast_array_utils.conv
+   :members:
+
+``fast_array_utils.conv.scipy``
+-------------------------------
+
+.. automodule:: fast_array_utils.conv.scipy
+   :members:

docs/index.rst

@@ -5,32 +5,10 @@
    :hidden:
 
    fast-array-utils <self>
+   conv
+   stats
+   typing
    testing
 
 .. automodule:: fast_array_utils
    :members:
-
-``fast_array_utils.types``
---------------------------
-
-.. automodule:: fast_array_utils.types
-   :members: CSBase, CSDataset
-
-``fast_array_utils.typing``
----------------------------
-
-.. automodule:: fast_array_utils.typing
-   :members:
-
-``fast_array_utils.conv``
--------------------------
-
-.. automodule:: fast_array_utils.conv
-   :members:
-
-
-``fast_array_utils.stats``
---------------------------
-
-.. automodule:: fast_array_utils.stats
-   :members:

docs/stats.rst

@@ -0,0 +1,5 @@
+``fast_array_utils.stats``
+==========================
+
+.. automodule:: fast_array_utils.stats
+   :members:

docs/typing.rst

@@ -0,0 +1,16 @@
+typing
+======
+
+The two submodules differ depending on their runtime properties:
+
+``fast_array_utils.types``
+--------------------------
+
+.. automodule:: fast_array_utils.types
+   :members: CSBase, CSDataset
+
+``fast_array_utils.typing``
+---------------------------
+
+.. automodule:: fast_array_utils.typing
+   :members:

pyproject.toml

@@ -67,8 +67,10 @@ installer = "uv"
 features = [ "doc" ]
 scripts.build = "sphinx-build -M html docs docs/_build"
 scripts.clean = "git clean -fdX docs"
+scripts.open = "python -m webbrowser -t docs/_build/html/index.html"
 
 [tool.hatch.envs.hatch-test]
+default-args = [  ]
 features = [ "test-min" ]
 extra-dependencies = [ "ipykernel", "ipycytoscape" ]
 env-vars.CODSPEED_PROFILE_FOLDER = "test-data/codspeed"
@@ -87,6 +89,8 @@ extras = [ "full", "default", "min" ]
 [tool.ruff]
 line-length = 100
 namespace-packages = [ "src/testing" ]
+format.preview = true
+format.docstring-code-format = true
 lint.select = [ "ALL" ]
 lint.ignore = [
   "A005",    # submodules never shadow builtins.
@@ -113,7 +117,6 @@ lint.per-file-ignores."tests/**/*.py" = [
 lint.per-file-ignores."typings/**/*.pyi" = [ "A002", "F403", "F405", "N801" ] # Stubs don’t follow name conventions
 lint.allowed-confusables = [ "×", "’" ]
 lint.flake8-bugbear.extend-immutable-calls = [ "testing.fast_array_utils.Flags" ]
-
 lint.flake8-copyright.notice-rgx = "SPDX-License-Identifier: MPL-2\\.0"
 lint.flake8-type-checking.exempt-modules = [  ]
 lint.flake8-type-checking.strict = true

src/fast_array_utils/__init__.py

@@ -1,5 +1,17 @@
 # SPDX-License-Identifier: MPL-2.0
-"""Fast array utils."""
+"""Fast array utilities with minimal dependencies.
+
+:mod:`fast_array_utils.conv`
+    This submodule is always available and contains conversion utilities.
+
+:mod:`fast_array_utils.stats`
+    This submodule requires :doc:`numba <numba:index>` to be installed
+    and contains statistics utilities.
+
+:mod:`fast_array_utils.typing` and :mod:`fast_array_utils.types`
+    These submodules contain types for annotations and checks, respectively.
+    Stubs for these types are available even if the respective packages are not installed.
+"""
 
 from __future__ import annotations
 

src/fast_array_utils/conv/__init__.py

@@ -25,22 +25,26 @@ def to_dense(
     x: CpuArray | DiskArray | types.sparray | types.spmatrix | types.CSDataset,
     /,
     *,
-    to_memory: bool = False,
+    to_cpu_memory: bool = False,
 ) -> NDArray[Any]: ...
 
 
 @overload
-def to_dense(x: types.DaskArray, /, *, to_memory: Literal[False] = False) -> types.DaskArray: ...
+def to_dense(
+    x: types.DaskArray, /, *, to_cpu_memory: Literal[False] = False
+) -> types.DaskArray: ...
 @overload
-def to_dense(x: types.DaskArray, /, *, to_memory: Literal[True]) -> NDArray[Any]: ...
+def to_dense(x: types.DaskArray, /, *, to_cpu_memory: Literal[True]) -> NDArray[Any]: ...
 
 
 @overload
 def to_dense(
-    x: GpuArray | types.CupySpMatrix, /, *, to_memory: Literal[False] = False
+    x: GpuArray | types.CupySpMatrix, /, *, to_cpu_memory: Literal[False] = False
 ) -> types.CupyArray: ...
 @overload
-def to_dense(x: GpuArray | types.CupySpMatrix, /, *, to_memory: Literal[True]) -> NDArray[Any]: ...
+def to_dense(
+    x: GpuArray | types.CupySpMatrix, /, *, to_cpu_memory: Literal[True]
+) -> NDArray[Any]: ...
 
 
 def to_dense(
@@ -54,20 +58,24 @@ def to_dense(
     | types.CupySpMatrix,
     /,
     *,
-    to_memory: bool = False,
+    to_cpu_memory: bool = False,
 ) -> NDArray[Any] | types.DaskArray | types.CupyArray:
-    """Convert x to a dense array.
+    r"""Convert x to a dense array.
+
+    If ``to_cpu_memory`` is :data:`False`, :class:`dask.array.Array`\ s and
+    :class:`cupy.ndarray`\ s/:class:`cupyx.scipy.sparse.spmatrix` instances
+    stay out-of-core and in GPU memory, respecively.
 
     Parameters
     ----------
     x
         Input object to be converted.
-    to_memory
+    to_cpu_memory
         Also load data into memory (resulting in a :class:`numpy.ndarray`).
 
     Returns
     -------
     Dense form of ``x``
 
     """
-    return to_dense_(x, to_memory=to_memory)
+    return to_dense_(x, to_cpu_memory=to_cpu_memory)

src/fast_array_utils/conv/_to_dense.py

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: MPL-2.0
 from __future__ import annotations
 
-from functools import singledispatch
+from functools import partial, singledispatch
 from typing import TYPE_CHECKING, cast
 
 import numpy as np
@@ -28,42 +28,46 @@ def to_dense_(
     | types.CupySpMatrix,
     /,
     *,
-    to_memory: bool = False,
+    to_cpu_memory: bool = False,
 ) -> NDArray[Any] | types.CupyArray | types.DaskArray:
-    del to_memory  # it already is
+    del to_cpu_memory  # it already is
     return np.asarray(x)
 
 
 @to_dense_.register(types.spmatrix | types.sparray)  # type: ignore[call-overload,misc]
-def _to_dense_cs(x: types.spmatrix | types.sparray, /, *, to_memory: bool = False) -> NDArray[Any]:
+def _to_dense_cs(
+    x: types.spmatrix | types.sparray, /, *, to_cpu_memory: bool = False
+) -> NDArray[Any]:
     from . import scipy
 
-    del to_memory  # it already is
+    del to_cpu_memory  # it already is
     return scipy.to_dense(x)
 
 
 @to_dense_.register(types.DaskArray)
 def _to_dense_dask(
-    x: types.DaskArray, /, *, to_memory: bool = False
+    x: types.DaskArray, /, *, to_cpu_memory: bool = False
 ) -> NDArray[Any] | types.DaskArray:
     from . import to_dense
 
-    x = x.map_blocks(lambda x: to_dense(x, to_memory=to_memory))
-    return x.compute() if to_memory else x  # type: ignore[return-value]
+    x = x.map_blocks(partial(to_dense, to_cpu_memory=to_cpu_memory))
+    return x.compute() if to_cpu_memory else x  # type: ignore[return-value]
 
 
 @to_dense_.register(types.CSDataset)
-def _to_dense_ooc(x: types.CSDataset, /, *, to_memory: bool = False) -> NDArray[Any]:
+def _to_dense_ooc(x: types.CSDataset, /, *, to_cpu_memory: bool = False) -> NDArray[Any]:
     from . import to_dense
 
-    if not to_memory:
-        msg = "to_memory must be True if x is an CS{R,C}Dataset"
+    if not to_cpu_memory:
+        msg = "to_cpu_memory must be True if x is an CS{R,C}Dataset"
         raise ValueError(msg)
     # TODO(flying-sheep): why is to_memory of type Any?  # noqa: TD003
     return to_dense(cast("types.CSBase", x.to_memory()))
 
 
 @to_dense_.register(types.CupyArray | types.CupySpMatrix)  # type: ignore[call-overload,misc]
-def _to_dense_cupy(x: GpuArray, /, *, to_memory: bool = False) -> NDArray[Any] | types.CupyArray:
+def _to_dense_cupy(
+    x: GpuArray, /, *, to_cpu_memory: bool = False
+) -> NDArray[Any] | types.CupyArray:
     x = x.toarray() if isinstance(x, types.CupySpMatrix) else x
-    return x.get() if to_memory else x
+    return x.get() if to_cpu_memory else x