add extension functionality (see #111)

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning][].
 [keep a changelog]: https://keepachangelog.com/en/1.1.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
 
+## [0.3.4] (unreleased)
+
+### Added
+
+- `mudata.register_mudata_namespace()` functionality for adding custom functionality to `MuData` objects.
+
 ## [0.3.3]
 
 ### Fixed
@@ -129,7 +135,8 @@ To copy the annotations explicitly, you will need to use `pull_obs()` and/or `pu
 
 Initial `mudata` release with `MuData`, previously a part of the `muon` framework.
 
-[0.3.3]: https://github.com/scverse/mudata/compare/v0.3.1...v0.3.3
+[0.3.4]: https://github.com/scverse/mudata/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/scverse/mudata/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/scverse/mudata/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/scverse/mudata/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/scverse/mudata/compare/v0.2.4...v0.3.0

docs/api.md

@@ -26,7 +26,39 @@
 ## Input/Output
 
 ```{eval-rst}
-.. automodsumm:: mudata
-   :functions-only:
+.. module::mudata
+.. autosummary::
+   :toctree: generated
+
+   to_anndata
+   to_mudata
+   concat
+   read
+   read_h5ad
+   read_anndata
+   read_h5mu
+   read_zarr
+   write
+   write_h5ad
+   write_anndata
+   write_h5mu
+   write_zarr
+```
+
+## Extensions
+```{eval-rst}
+.. module::mudata
+.. autosummary::
    :toctree: generated
+
+   register_mudata_namespace
+```
+
+Types used by the former:
+```{eval-rst}
+.. module::mudata
+.. autosummary::
+   :toctree: generated
+
+   ExtensionNamespace
 ```

docs/conf.py

@@ -62,7 +62,6 @@
     "sphinx_design",
     "IPython.sphinxext.ipython_console_highlighting",
     "sphinxext.opengraph",
-    "sphinx_automodapi.automodapi",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
 ]
 

docs/extensions/typed_returns.py

@@ -0,0 +1,32 @@
+# code from https://github.com/theislab/scanpy/blob/master/docs/extensions/typed_returns.py
+# with some minor adjustment
+from __future__ import annotations
+
+import re
+from collections.abc import Generator, Iterable
+
+from sphinx.application import Sphinx
+from sphinx.ext.napoleon import NumpyDocstring
+
+
+def _process_return(lines: Iterable[str]) -> Generator[str, None, None]:
+    for line in lines:
+        if m := re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line):
+            yield f"-{m['param']} (:class:`~{m['type']}`)"
+        else:
+            yield line
+
+
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:
+    lines_raw = self._dedent(self._consume_to_next_section())
+    if lines_raw[0] == ":":
+        del lines_raw[0]
+    lines = self._format_block(":returns: ", list(_process_return(lines_raw)))
+    if lines and lines[-1]:
+        lines.append("")
+    return lines
+
+
+def setup(app: Sphinx):
+    """Set app."""
+    NumpyDocstring._parse_returns_section = _parse_returns_section

pyproject.toml

@@ -34,6 +34,7 @@ dependencies = [
   "numpy",
   "pandas>=1.4",
   "scipy",
+  "scverse-misc",
   # for debug logging (referenced from the issue template)
   "session-info2",
 ]
@@ -63,7 +64,6 @@ doc = [
   "pandas",
   "sphinx>=8.1",
   "sphinx-autodoc-typehints",
-  "sphinx-automodapi",
   "sphinx-book-theme>=1",
   "sphinx-copybutton",
   "sphinx-design",

src/mudata/__init__.py

@@ -1,6 +1,8 @@
 """Multimodal datasets"""
 
 from anndata import AnnData
+from scverse_misc import ExtensionNamespace
+from scverse_misc import make_register_namespace_decorator as _make_register_namespace_decorator
 
 from ._core import utils
 from ._core.config import set_options
@@ -25,6 +27,8 @@
 __anndataversion__ = "0.1.0"
 __mudataversion__ = "0.1.0"
 
+register_mudata_namespace = _make_register_namespace_decorator(MuData, "mdata", "register_mudata_namespace", "numpy")
+
 __all__ = [
     "__version__",
     "MuData",
@@ -44,4 +48,6 @@
     "write_anndata",
     "write_h5mu",
     "write_zarr",
+    "register_mudata_namespace",
+    "ExtensionNamespace",
 ]