Documentation fixes / improvements

docs/_templates/autosummary/class.rst

@@ -8,52 +8,52 @@
 
 {% block attributes %}
 {% if attributes %}
-Attributes table
-~~~~~~~~~~~~~~~~
+    Attributes table
+    ~~~~~~~~~~~~~~~~
 
-.. autosummary::
-{% for item in attributes %}
-    ~{{ name }}.{{ item }}
-{%- endfor %}
-{% endif %}
-{% endblock %}
+    .. autosummary::
+    {% for item in attributes %}
+        ~{{ name }}.{{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
 
 {% block methods %}
 {% if methods %}
-Methods table
-~~~~~~~~~~~~~
-
-.. autosummary::
-{% for item in methods %}
-    {%- if item != '__init__' %}
-    ~{{ name }}.{{ item }}
-    {%- endif -%}
-{%- endfor %}
-{% endif %}
-{% endblock %}
+    Methods table
+    ~~~~~~~~~~~~~
+
+    .. autosummary::
+    {% for item in methods %}
+        {%- if item != '__init__' %}
+        ~{{ name }}.{{ item }}
+        {%- endif -%}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
 
 {% block attributes_documentation %}
 {% if attributes %}
-Attributes
-~~~~~~~~~~
+    Attributes
+    ~~~~~~~~~~
 
 {% for item in attributes %}
 
-.. autoattribute:: {{ [objname, item] | join(".") }}
+    .. auto{{ [fullname, item] | join(".") | member_type }}:: {{ [objname, item] | join(".") }}
 {%- endfor %}
 
 {% endif %}
 {% endblock %}
 
 {% block methods_documentation %}
 {% if methods %}
-Methods
-~~~~~~~
+    Methods
+    ~~~~~~~
 
 {% for item in methods %}
 {%- if item != '__init__' %}
 
-.. automethod:: {{ [objname, item] | join(".") }}
+    .. automethod:: {{ [objname, item] | join(".") }}
 {%- endif -%}
 {%- endfor %}
 

docs/api.md

@@ -1,22 +1,12 @@
 # API Reference
 
-```{contents}
-:depth: 3
-:local:
-```
-
-```{toctree}
-:maxdepth: 10
-```
-
 ```{eval-rst}
-.. currentmodule:: mudata
+.. module:: mudata
 ```
 
 ## Multimodal omics
 
 ```{eval-rst}
-.. module::mudata
 .. autosummary::
    :toctree: generated
 
@@ -26,7 +16,7 @@
 ## Input/Output
 
 ```{eval-rst}
-.. module::mudata
+.. currentmodule:: mudata
 .. autosummary::
    :toctree: generated
 
@@ -47,7 +37,6 @@
 
 ## Extensions
 ```{eval-rst}
-.. module::mudata
 .. autosummary::
    :toctree: generated
 
@@ -56,9 +45,16 @@
 
 Types used by the former:
 ```{eval-rst}
-.. module::mudata
 .. autosummary::
    :toctree: generated
 
    ExtensionNamespace
 ```
+
+## Settings
+```{eval-rst}
+.. autosummary::
+   :toctree: generated
+
+   set_options
+```

docs/conf.py

@@ -88,12 +88,20 @@
 
 source_suffix = {".rst": "restructuredtext", ".ipynb": "myst-nb", ".myst": "myst-nb"}
 
+# FIXME: remove this workaround when anndata 0.13 is released so docs are built with Pandas 3
+import pandas as pd  # noqa: E402
+
+pd.DataFrame.__module__ = "pandas"
+pd.Index.__module__ = "pandas"
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
     "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
     "fsspec": ("https://filesystem-spec.readthedocs.io/en/stable/", None),
+    "h5py": ("https://docs.h5py.org/en/stable/", None),
     "zarr": ("https://zarr.readthedocs.io/en/stable/", None),
 }
 

docs/extensions/member_type.py

@@ -0,0 +1,34 @@
+"""Extension adding a jinja2 filter that determines a class member’s type."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from jinja2.defaults import DEFAULT_FILTERS
+from jinja2.utils import import_string
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+def member_type(obj_path: str) -> Literal["method", "property", "attribute"]:
+    """Determine object member type.
+
+    E.g.: `.. auto{{ fullname | member_type }}::`
+    """
+    # https://jinja.palletsprojects.com/en/stable/api/#custom-filters
+    cls_path, member_name = obj_path.rsplit(".", 1)
+    cls = import_string(cls_path)
+    member = getattr(cls, member_name, None)
+    match member:
+        case property():
+            return "property"
+        case _ if callable(member):
+            return "method"
+        case _:
+            return "attribute"
+
+
+def setup(app: Sphinx):
+    """App setup hook."""
+    DEFAULT_FILTERS["member_type"] = member_type

pyproject.toml

@@ -55,6 +55,7 @@ doc = [
   "docutils>=0.8,!=0.18.*,!=0.19.*",
   "ipykernel",
   "ipython",
+  "mudata[io]",
   "myst-nb>=1.1",
   "pandas",
   "sphinx>=8.1",
@@ -64,7 +65,7 @@ doc = [
   "sphinx-design",
   "sphinxcontrib-bibtex>=1",
   "sphinxcontrib-katex",
-  "sphinxext-opengraph",
+  "sphinxext-opengraph"
 ]
 
 [tool.hatch]

src/mudata/_core/config.py

@@ -24,7 +24,7 @@ class set_options:
     >>> with mudata.set_options(display_style="html"):
     ...     print("Options are applied here")
 
-    ... or globally:
+    or globally:
 
     >>> mudata.set_options(display_style="html")
     """