docs: make ReadTheDocs build deps-free and reliable (D6)

.readthedocs.yaml

@@ -1,21 +1,19 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
+# .readthedocs.yaml — Read the Docs build configuration
+#
+# The heavy runtime dependencies (torch, scvi-tools, scanpy, pyro, ...) are NOT
+# installed here. They are mocked at build time via ``autodoc_mock_imports`` in
+# docs/conf.py, so the API reference builds from source without pulling the full
+# ML stack — which keeps the RTD build fast and avoids out-of-memory failures.
 version: 2
 
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.12"
 
 python:
   install:
     - requirements: docs/requirements.txt
-    - method: pip
-      path: .
 
 sphinx:
   configuration: docs/conf.py
-
-formats:
-  - pdf
-  - epub

docs/conf.py

@@ -12,12 +12,26 @@
 author = 'Nicholas Ceglia'
 
 # The full version, including alpha/beta/rc tags.
-# Single source of truth is pyproject.toml; read it back via installed metadata.
-try:
-    from importlib.metadata import version as _pkg_version
-    release = _pkg_version("tcri")
-except Exception:
-    release = "0.0.0"
+# Single source of truth is pyproject.toml. Prefer installed metadata; fall back
+# to parsing pyproject.toml directly so the version is correct even when the
+# package is not installed in the docs environment (e.g. on ReadTheDocs, where
+# the heavy runtime deps are mocked rather than installed).
+def _get_release():
+    try:
+        from importlib.metadata import version as _pkg_version
+        return _pkg_version("tcri")
+    except Exception:
+        pass
+    try:
+        import tomllib  # Python 3.11+
+        _pp = os.path.join(os.path.dirname(__file__), os.pardir, "pyproject.toml")
+        with open(_pp, "rb") as _f:
+            return tomllib.load(_f)["project"]["version"]
+    except Exception:
+        return "0.0.0"
+
+
+release = _get_release()
 version = release
 
 # -- General configuration ---------------------------------------------------
@@ -80,6 +94,11 @@
 # -- Options for autodoc extension -------------------------------------------
 autodoc_member_order = 'bysource'
 autodoc_typehints = 'description'
+# Read constructor signatures from ``__init__`` directly. Without this, classes
+# whose (mocked) base injects ``__new__(*args, **kwargs)`` — e.g. TCRIModel via
+# scvi's BaseModelClass — would render as ``TCRIModel(*args, **kwargs)`` on the
+# deps-mocked ReadTheDocs build.
+autodoc_class_signature = 'separated'
 autodoc_default_options = {
     'members': True,
     'undoc-members': True,
@@ -90,9 +109,27 @@
 add_module_names = False
 # Generate stub pages for any autosummary directives.
 autosummary_generate = True
-# Don't fail the whole build if an optional/heavy import is unavailable at
-# doc-build time; autodoc will note the missing object instead.
-autodoc_mock_imports = []
+# Mock the heavy / native scientific dependencies so the API reference can be
+# built from source without installing the full ML stack (torch, scvi-tools,
+# scanpy, ...). autodoc still reads the real signatures and docstrings of TCRi's
+# own code; only third-party imports are stubbed. numpy and pandas are kept real
+# (they're light and let intersphinx resolve their types).
+autodoc_mock_imports = [
+    "torch",
+    "pyro",
+    "scvi",
+    "sklearn",
+    "scanpy",
+    "anndata",
+    "scipy",
+    "matplotlib",
+    "seaborn",
+    "mpltern",
+    "umap",
+    "tqdm",
+    "daft",
+    "gseapy",
+]
 
 # -- Options for napoleon extension ------------------------------------------
 napoleon_google_docstring = True

docs/requirements.txt

@@ -1,9 +1,11 @@
-sphinx>=4.0.0
-sphinx_rtd_theme>=1.0.0
-myst-parser>=0.15.0
-scipy
+# Documentation build dependencies — intentionally light.
+#
+# The package's heavy runtime deps (torch, scvi-tools, scanpy, pyro, mpltern,
+# ...) are mocked via autodoc_mock_imports in conf.py, so they are NOT listed
+# here. Only the Sphinx toolchain plus numpy/pandas (kept real for clean
+# intersphinx type links) are needed.
+sphinx>=7,<9
+sphinx-rtd-theme>=2.0
+myst-parser>=2.0
 numpy
-scanpy
 pandas
-matplotlib
-seaborn