Documentation fixes / improvements

[ilia-kats]

• fix attribute cross-references
• document set_options
• document all function arguments (particularly the IO module was bad at this), make terminology more consistent (e.g. always use features), use better and more complete type hints

[codecov]

Codecov Report

❌ Patch coverage is 97.22222% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.98%. Comparing base (2b59c58) to head (02f5643).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/mudata/_core/io.py	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #130      +/-   ##
==========================================
- Coverage   91.05%   90.98%   -0.08%     
==========================================
  Files          11       11              
  Lines        1800     1797       -3     
==========================================
- Hits         1639     1635       -4     
- Misses        161      162       +1     

Files with missing lines	Coverage Δ
src/mudata/_core/config.py	90.90% <ø> (ø)
src/mudata/_core/merge.py	83.33% <ø> (ø)
src/mudata/_core/mudata.py	93.12% <100.00%> (-0.03%)	⬇️
src/mudata/_core/to_.py	88.00% <ø> (ø)
src/mudata/_core/io.py	94.98% <83.33%> (-0.29%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ilan-gold]

For some reason I literally can't comment on this line-by-line but the biggest thing that stands out is that public APIs like MuData.obsm have no typed documentation i.e., what is the API they promise: https://mudata--130.org.readthedocs.build/130/generated/mudata.MuData.html#mudata.MuData.obsm

but this is possible: https://anndata.readthedocs.io/en/stable/generated/anndata.AnnData.obsm.html#anndata.AnnData.obsm

[ilia-kats]

Good catch, I actually didn't pay attention to this. I will investigate, but it seems like an issue with the cookiecutter template, it's the same for mofaflex.

[ilia-kats]

OK, so the difference here is that AnnData lets autosummary generate individual pages for each property, so autosummary knows what is an attribute and what is a property and can use autoattribute or autoproperty accordingly. The cookiecutter template puts everything on one page and alwas uses autoattribute, since this works for both properties and attributes, whereas autoproperty apparently crashes when used with attributes. There is not enough information in the template namespace to decide when to use one or the other (@flying-sheep already opened a Sphinx issue about this).

For the moment, I would like to avoid diverging too much from the template.

[ilan-gold]

Wow this is pretty bad ok. Then let's leave it out for now. Or we can wait until Phil replies tomorrow, up to you.

[ilia-kats]

I don't think this PR is super urgent, I can wait a few days

[flying-sheep]

if you feel like investing time into this, you could add an extension like this:

"""Extension adding a jinja2 filter that determines a class member’s type."""

from __future__ import annotations

from inspect import get_annotations
from typing import TYPE_CHECKING

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

[ilan-gold]

Do you support pandas>=3? Why not point at the 2.x series docs?

[ilan-gold]

Ok yea so there is something wrong with the docs configuration: https://app.readthedocs.org/projects/mudata/builds/31968777/ has

/home/docs/checkouts/readthedocs.org/user_builds/mudata/checkouts/130/src/mudata/__init__.py:docstring of mudata.MuData.obsm:3: WARNING: py:class reference target not found: pandas.DataFrame [ref.class]
/home/docs/checkouts/readthedocs.org/user_builds/mudata/checkouts/130/src/mudata/__init__.py:docstring of mudata.MuData.varm:3: WARNING: py:class reference target not found: pandas.DataFrame [ref.class]
<unknown>:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame [ref.class]
<unknown>:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame [ref.class]

but I would think this should error out

[ilia-kats]

We do technically support pands 3, I think. At least the scverse integration test pipeline passes with pandas 3. So as soon as AnnData 0.13 is released we should be good to go.

I did however forget to put Pandas in the intersphinx mapping dict, this is fixed now. I also added a workaround for now to still be able to link to pandas 3 docs, though I'm not sure if this is the best solution for this.

I disabled erroring out for missing links at some point, a) because we had quite many of those before this PR (e..g. here) and b) because I don't think that a few missing links should make the entire pipeline fail.

[ilan-gold]

Whenever you're ready, looks good by me. Feel free to ping Phil for his opinion on zulip

[flying-sheep]

looks good to me too. You might want to add that extension if you want, and please while you’re at the templates, adopt the “if no methods/attributes, don’t show methods/attributes header” changes from here: https://github.com/scverse/anndata/pull/2298/changes#diff-b8b6e67f064e921ecb963b837406d9e056dedcb77f1d9f03cbc1d32e7867e9a6

you might also want to use scanpydoc.definition_list_typed_field to keep parameters displaying as definition list

but all these are nitpicks.

[ilia-kats]

Thanks for the extension, I added it and it works!

Regarding the “if no methods/attributes, don’t show methods/attributes header” comment, there is only one user-exposed (documented) class in this package, so this is not urgent and can wait until the next cookiecutter template update, which will (hopefully?) contain an analogous change as part of scverse/cookiecutter-scverse#483 (if you don't mind, I will also add the extension to that PR).

Similarly, other users of the cookiecutter template can presumably also benefit from scanpydoc, so I'd prefer adding it there.

[flying-sheep]

I added it and it works!

oh wow, old school coding: I typed that directly into that GitHub comment textfield, no testing no nothing.

I think it’s pretty robust as it’ll e.g. handle fields that don’t exist on a class (e.g. because they’re just member: type and are therefore not attributes of the class).