Docs/nitpicky (#500)

* Fix most links

* Document __call__

* Fix last link

* Enable docs linter in CI, disable spellcheck

* Checkout submodules in CI

* [ci skip] Fix typo

.github/workflows/lint.yml

@@ -19,11 +19,12 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # TODO(michalk8): enable in the future
-        lint-kind: [code] # , docs]
+        lint-kind: [code, docs]
 
     steps:
       - uses: actions/checkout@v3
+        with:
+          submodules: true
       - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:

.pre-commit-config.yaml

@@ -52,7 +52,7 @@ repos:
       - id: blacken-docs
         additional_dependencies: [black==23.1.0]
   - repo: https://github.com/rstcheck/rstcheck
-    rev: v6.1.1
+    rev: v6.1.2
     hooks:
       - id: rstcheck
         additional_dependencies: [tomli]
@@ -63,7 +63,7 @@ repos:
       - id: doc8
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     # Ruff version.
-    rev: v0.0.252
+    rev: v0.0.257
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

docs/_templates/autosummary/class.rst

@@ -10,7 +10,12 @@
     .. autosummary::
         :toctree: .
     {% for item in methods %}
-    {%- if item not in ['__init__', 'tree_flatten', 'tree_unflatten', 'bind'] %}
+    {%- if item not in ['__init__'] %}
+        ~{{ name }}.{{ item }}
+    {%- endif %}
+    {%- endfor %}
+    {%- for item in all_methods %}
+    {%- if item in ['__call__'] %}
         ~{{ name }}.{{ item }}
     {%- endif %}
     {%- endfor %}

docs/conf.py

@@ -59,6 +59,18 @@
 pygments_style = "tango"
 pygments_dark_style = "monokai"
 
+nitpicky = True
+nitpick_ignore = [
+    ("py:class", "numpy.float64"),
+]
+# TODO(michalk8): remove once typing has been cleaned-up
+nitpick_ignore_regex = [
+    (r"py:class", r"moscot\..*(K|B|O)"),
+    (r"py:class", r"numpy\._typing.*"),
+    (r"py:class", r"moscot\..*Protocol.*"),
+]
+
+
 # bibliography
 bibtex_bibfiles = ["references.bib"]
 bibtex_reference_style = "author_year"
@@ -87,7 +99,6 @@
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 
-
 # spelling
 spelling_lang = "en_US"
 spelling_warning = True
@@ -101,6 +112,11 @@
     "enchant.tokenize.MentionFilter",
 ]
 
+linkcheck_ignore = [
+    # 403 Client Error
+    r"https://doi.org/10.1126/science.aad0501",
+]
+
 exclude_patterns = ["_build", "**.ipynb_checkpoints", "notebooks/README.rst", "notebooks/CONTRIBUTING.rst"]
 
 # -- Options for HTML output -------------------------------------------------

docs/developer.rst

@@ -1,9 +1,6 @@
 Developer API
 #############
 
-.. module:: moscot
-    :noindex:
-
 Backends
 ~~~~~~~~
 .. module:: moscot.backends
@@ -15,6 +12,9 @@ Backends
     backends.ott.GWSolver
     backends.ott.OTTOutput
 
+    backends.utils.get_solver
+    backends.utils.get_available_backends
+
 Costs
 ~~~~~
 .. module:: moscot.costs
@@ -43,7 +43,7 @@ Problems
     problems.BirthDeathProblem
     problems.BaseCompoundProblem
     problems.CompoundProblem
-    problems.ProblemManager
+    cost.BaseCost
 
 Mixins
 ^^^^^^
@@ -55,12 +55,14 @@ Mixins
 
 Solvers
 ^^^^^^^
+.. module:: moscot.solvers
 .. currentmodule:: moscot.base
 .. autosummary::
     :toctree: genapi
 
     solver.BaseSolver
     solver.OTSolver
+    output.BaseSolverOutput
 
 Output
 ^^^^^^
@@ -80,6 +82,7 @@ Policies
 .. autosummary::
     :toctree: genapi
 
+    subset_policy.SubsetPolicy
     subset_policy.StarPolicy
     subset_policy.ExternalStarPolicy
     subset_policy.ExplicitPolicy
@@ -97,3 +100,10 @@ Miscellaneous
     data.apoptosis_markers
     tagged_array.TaggedArray
     tagged_array.Tag
+
+.. currentmodule:: moscot.base.problems
+.. autosummary::
+    :toctree: genapi
+
+    birth_death.beta
+    birth_death.delta

pyproject.toml

@@ -289,7 +289,8 @@ set_env = SPHINXOPTS = -W -q --keep-going
 changedir = {tox_root}{/}docs
 commands =
     make linkcheck {posargs}
-    make spelling {posargs}
+    # TODO(michalk8): uncomment after https://github.com/theislab/moscot/issues/490
+    # make spelling {posargs}
 
 [testenv:clean-docs]
 description = Remove the documentation.

src/moscot/_docs/_docs.py

@@ -9,26 +9,26 @@
 """
 _adata_x = """\
 adata_x
-    Instance of :class:`anndata.AnnData` containing the data of the source distribution.
+    Instance of :class:`~anndata.AnnData` containing the data of the source distribution.
 """
 _adata_y = """\
 adata_y
-    Instance of :class:`anndata.AnnData` containing the data of the target distribution.
+    Instance of :class:`~anndata.AnnData` containing the data of the target distribution.
 """
 _solver = """\
 solver
     Instance from :mod:`moscot.solvers` used for solving the Optimal Transport problem.
 """
 _source = """\
 source
-    Value in :attr:`anndata.AnnData.obs` defining the assignment to the source distribution."""
+    Value in :attr:`~anndata.AnnData.obs` defining the assignment to the source distribution."""
 _target = """\
 target
-    Value in :attr:`anndata.AnnData.obs` defining the assignment to the target distribution.
+    Value in :attr:`~anndata.AnnData.obs` defining the assignment to the target distribution.
 """
 _reference = """\
 reference
-    `reference` in :class:`moscot.problems._subset_policy.StarPolicy`.
+    `reference` in the :class:`~moscot.utils.subset_policy.StarPolicy`.
 """
 _xy_callback = """\
 xy_callback
@@ -86,7 +86,7 @@
     - If `data` is a :class:`str` this should correspond to a column in :attr:`anndata.AnnData.obs`.
       The transport map is applied to the subset corresponding to the source distribution
       (if `forward` is `True`) or target distribution (if `forward` is :obj:`False`) of that column.
-    - If `data` is a :class:npt.ArrayLike the transport map is applied to `data`.
+    - If `data` is a :class:`numpy.ndarray`, the transport map is applied to `data`.
     - If `data` is a :class:`dict` then the keys should correspond to the tuple defining a single optimal
       transport map and the value should be one of the two cases described above.
 """
@@ -96,23 +96,12 @@
 """
 _marginal_kwargs = r"""
 marginal_kwargs
-    Keyword arguments for :meth:`~moscot.problems.BirthDeathProblem._estimate_marginals`. If ``'scaling'``
+    Keyword arguments for :meth:`~moscot.base.problems.BirthDeathProblem.estimate_marginals`. If ``'scaling'``
     is in ``marginal_kwargs``, the left marginals are computed as
     :math:`\exp(\frac{(\textit{proliferation} - \textit{apoptosis}) \cdot (t_2 - t_1)}{\textit{scaling}})`.
     Otherwise, the left marginals are computed using a birth-death process. The keyword arguments
-    are either used for :func:`~moscot.problems.time._utils.beta`, i.e. one of:
-
-        - beta_max: float
-        - beta_min: float
-        - beta_center: float
-        - beta_width: float
-
-    or for :func:`~moscot.problems.time._utils.delta`, i.e. one of:
-
-        - delta_max: float
-        - delta_min: float
-        - delta_center: float
-        - delta_width: float
+    are either used for :func:`~moscot.base.problems.birth_death.beta` or
+    :func:`~moscot.base.problems.birth_death.delta`.
 """
 _shape = """\
 shape
@@ -140,10 +129,10 @@
 a
     Specifies the left marginals. If
         - ``a`` is :class:`str` - the left marginals are taken from :attr:`anndata.AnnData.obs`,
-        - if :meth:`~moscot.problems.base._birth_death.BirthDeathMixin.score_genes_for_marginals` was run and
+        - if :meth:`score_genes_for_marginals` was run and
           if ``a`` is `None`, marginals are computed based on a birth-death process as suggested in
           :cite:`schiebinger:19`,
-        - if :meth:`~moscot.problems.base._birth_death.BirthDeathMixin.score_genes_for_marginals` was run and
+        - if :meth:`score_genes_for_marginals` was run and
           if ``a`` is `None`, and additionally ``'scaling'`` is provided in ``marginal_kwargs``,
           the marginals are computed as
           :math:`\exp(\frac{(\textit{proliferation} - \textit{apoptosis}) \cdot (t_2 - t_1)}{\textit{scaling}})`
@@ -154,7 +143,7 @@
 b
     Specifies the right marginals. If
         - ``b`` is :class:`str` - the left marginals are taken from :attr:`anndata.AnnData.obs`,
-        - if :meth:`~moscot.problems.base._birth_death.BirthDeathMixin.score_genes_for_marginals` was run
+        - if :meth:`score_genes_for_marginals` was run
           uniform (mean of left marginals) right marginals are used,
         - otherwise or if ``b`` is :obj:`False`, uniform marginals are used.
 """

src/moscot/_docs/_docs_mixins.py

@@ -57,7 +57,7 @@
 """
 _return_cell_transition = "Transition matrix of cells or groups of cells."
 _notes_cell_transition = """\
-To visualise the results, see :func:`moscot.pl.cell_transition`.
+To visualize the results, see :func:`moscot.plotting.cell_transition`.
 """
 _normalize = """\
 normalize
@@ -82,7 +82,7 @@
     - If `data` is a :class:`str` this should correspond to a column in :attr:`anndata.AnnData.obs`.
       The transport map is applied to the subset corresponding to the source distribution
       (if `forward` is `True`) or target distribution (if `forward` is `False`) of that column.
-    - If `data` is a :class:npt.ArrayLike the transport map is applied to `data`.
+    - If `data` is a :class:`numpy.ndarray` the transport map is applied to `data`.
     - If `data` is a :class:`dict` then the keys should correspond to the tuple defining a single optimal
       transport map and the value should be one of the two cases described above.
 """

src/moscot/_docs/_docs_plot.py

@@ -18,15 +18,15 @@
 """
 _cbar_kwargs_cell_transition = """\
 cbar_kwargs
-    Keyword arguments for :func:`matplotlib.figure.Figure.colorbar`."""
+    Keyword arguments for :meth:`~matplotlib.figure.Figure.colorbar`."""
 # return cell transition
 _return_cell_transition = """\
-:class:`matplotlib.figure.Figure` heatmap of cell transition matrix.
+Heatmap of cell transition matrix.
 """
 # notes cell transition
 _notes_cell_transition = """\
-This function looks for the following data in the :class:`anndata.AnnData` object
-which is passed or saved as an attribute of :mod:`moscot.problems.base.CompoundProblem`.
+This function looks for the following data in the :class:`~anndata.AnnData` object
+which is passed or saved as an attribute of :class:`moscot.base.problems.CompoundProblem`.
 
     - `transition_matrix`
     - `source`
@@ -57,16 +57,16 @@
 """
 # notes sankey
 _notes_sankey = """\
-This function looks for the following data in the :class:`anndata.AnnData` object
-which is passed or saved as an attribute of :mod:`moscot.problems.base.CompoundProblem`.
+This function looks for the following data in the :class:`~anndata.AnnData` object
+which is passed or saved as an attribute of :class:`moscot.base.problems.CompoundProblem`.
 
     - `transition_matrices`
     - `captions`
     - `key`
 """
 _alpha_transparency = """\
 alpha
-    Transparancy value.
+    Transparency value.
 """
 _interpolate_color = """\
 interpolate_color
@@ -102,12 +102,12 @@
 """
 # return push/pull
 _return_push_pull = """\
-:class:`matplotlib.figure.Figure` scatterplot in `basis` coordinates.
+Scatterplot in `basis` coordinates.
 """
 # notes push/pull
 _notes_push_pull = """\
-This function looks for the following data in the :class:`anndata.AnnData` object
-which is passed or saved as an attribute of :mod:`moscot.problems.base.CompoundProblem`.
+This function looks for the following data in the :class:`~anndata.AnnData` object
+which is passed or saved as an attribute of :class:`moscot.base.problems.CompoundProblem`.
 
     - `temporal_key`
 """
@@ -116,7 +116,7 @@
 # general input
 _input_plotting = """\
 inp
-    An instance of :class:`anndata.AnnData` where the results of the corresponding method
+    An instance of :class:`~anndata.AnnData` where the results of the corresponding method
     of the :mod:`moscot.problems` instance is saved.
     Alternatively, the instance of the moscot problem can be passed, too."""
 _uns_key = """\
@@ -125,7 +125,7 @@
     of the moscot problem instance is saved."""
 _cmap = """\
 cmap
-    Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`."""
+    Colormap for continuous annotations, see :class:`~matplotlib.colors.Colormap`."""
 _title = """\
 title
     Title of the plot.
@@ -149,7 +149,7 @@
     Whether to return the figure."""
 _ax = f"""\
 ax
-    Axes, :class:`matplotlib.axes.Axes`.
+    Axes.
 {_return_fig}"""
 _figsize_dpi_save = f"""\
 figsize

src/moscot/backends/__init__.py

@@ -1,11 +1,4 @@
-from typing import Tuple
-
 from moscot.backends import ott
-from moscot.backends.utils import get_solver, register_solver
+from moscot.backends.utils import get_available_backends, get_solver, register_solver
 
 __all__ = ["ott", "get_solver", "register_solver", "get_available_backends"]
-
-
-def get_available_backends() -> Tuple[str, ...]:
-    """TODO."""
-    return ("ott",)

src/moscot/backends/utils.py

@@ -1,12 +1,12 @@
-from typing import TYPE_CHECKING, Any, Literal, Union
+from typing import TYPE_CHECKING, Any, Literal, Tuple, Union
 
 from moscot import _registry
 from moscot._types import ProblemKind_t
 
 if TYPE_CHECKING:
     from moscot.backends import ott
 
-__all__ = ["get_solver", "register_solver"]
+__all__ = ["get_solver", "register_solver", "get_available_backends"]
 
 
 _REGISTRY = _registry.Registry()
@@ -33,3 +33,8 @@ def _(problem_kind: Literal["linear", "quadratic"], **kwargs: Any) -> Union["ott
     if problem_kind == "quadratic":
         return ott.GWSolver(**kwargs)
     raise NotImplementedError(f"Unable to create solver for `{problem_kind!r}` problem.")
+
+
+def get_available_backends() -> Tuple[str, ...]:
+    """TODO."""
+    return tuple(backend for backend in _REGISTRY)