Docs/refactor apidocs

.github/workflows/ci.yml

@@ -90,7 +90,23 @@ jobs:
       - name: Build Docs
         run: |
           pip install tox-uv
-          tox -e docs-py310 -- -r
+          tox -e docs-py310
+
+  linkcheck:
+    name: "Link Check"
+    runs-on: ubuntu-latest
+    needs: [lint]
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with: {python-version: "3.10"}
+      - name: Check external links
+        run: |
+          pip install tox-uv
+          tox -e linkcheck
 
   typecheck:
     needs: [lint]

baybe/recommenders/meta/base.py

@@ -52,7 +52,8 @@ def get_non_meta_recommender(
     ) -> RecommenderProtocol:
         """Follow the meta recommender chain to the selected non-meta recommender.
 
-        Recursively calls :meth:`MetaRecommender.select_recommender` until a
+        Recursively calls
+        :meth:`~baybe.recommenders.meta.base.MetaRecommender.select_recommender` until a
         non-meta recommender is encountered, which is then returned.
         Effectively, this extracts the recommender responsible for generating
         the recommendations for the specified context.

baybe/surrogates/gaussian_process/core.py

@@ -306,7 +306,7 @@ def posterior_mean_function(
         * **Eagerly:** By calling the method and passing the returned module to a GP.
         * **Lazily:** By passing the bound method itself, without eagerly calling it.
             This works because the method signature complies with
-            :class:`~.components.mean.MeanFactoryProtocol`, i.e., the new GP will use it
+            :obj:`~.components.mean.MeanFactoryProtocol`, i.e., the new GP will use it
             as a factory and call it automatically at fit time.
 
         If the mean-providing GP has not been fitted at call time, its prior mean module

baybe/transformations/base.py

@@ -43,10 +43,11 @@ def get_codomain(self, interval: Interval | None = None, /) -> Interval:
         In accordance with the mathematical definition of a function's `codomain
         <https://en.wikipedia.org/wiki/Codomain>`_, we define the codomain of a given
         :class:`~baybe.utils.interval.Interval` under a certain (assumed continuous)
-        :class:`~Transformation` to be an :class:`~baybe.utils.interval.Interval`
-        guaranteed to contain all possible outcomes when the :class:`~Transformation` is
-        applied to all points in the input :class:`~baybe.utils.interval.Interval`. In
-        cases where the image cannot exactly be computed, it is often still possible to
+        :class:`~baybe.transformations.base.Transformation` to be an
+        :class:`~baybe.utils.interval.Interval` guaranteed to contain all possible
+        outcomes when the :class:`~baybe.transformations.base.Transformation` is applied
+        to all points in the input :class:`~baybe.utils.interval.Interval`. In cases
+        where the image cannot exactly be computed, it is often still possible to
         compute a codomain. The codomain always contains the image, but might be larger.
         """
 
@@ -56,10 +57,10 @@ def get_image(self, interval: Interval | None = None, /) -> Interval:
         In accordance with the mathematical definition of a function's `image
         <https://en.wikipedia.org/wiki/Image_(mathematics)>`_, we define the image of a
         given :class:`~baybe.utils.interval.Interval` under a certain (assumed
-        continuous) :class:`~Transformation` to be the smallest
-        :class:`~baybe.utils.interval.Interval` containing all possible outcomes when
-        the :class:`~Transformation` is applied to all points in the input
-        :class:`~baybe.utils.interval.Interval`.
+        continuous) :class:`~baybe.transformations.base.Transformation` to be the
+        smallest :class:`~baybe.utils.interval.Interval` containing all possible
+        outcomes when the :class:`~baybe.transformations.base.Transformation` is applied
+        to all points in the input :class:`~baybe.utils.interval.Interval`.
         """
         # By default, it is assumed that the exact image of an interval cannot be
         # computed but only the codomain is available (see :meth:`get_codomain`).

docs/api_reference.md

@@ -0,0 +1,17 @@
+---
+orphan: true
+---
+
+<!-- This page exists solely to trigger the recursive autosummary stub generation for
+the API reference. The generated `_autosummary/baybe` tree is linked from the "API
+Reference" entry of the main toctree in `index.md`. Keeping the directive off the
+landing page prevents the module summary table from being rendered there. -->
+
+```{eval-rst}
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   baybe
+```

docs/components/transformations.md

@@ -399,7 +399,7 @@ t = CustomTransformation(torch.sin)
 ```
 
 ````{admonition} Automatic Wrapping
-:note:
+:class: note
 
 When embedding custom transformations into another context, wrapping the `torch`
 callable into a {class}`~baybe.transformations.basic.CustomTransformation` happens

docs/conf.py

@@ -4,9 +4,6 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-import os
-import shutil
-
 from gpytorch.kernels import Kernel as GPyTorchKernel
 from gpytorch.likelihoods import Likelihood as GPyTorchLikelihood
 from gpytorch.means import Mean as GPyTorchMean
@@ -48,16 +45,6 @@
 
 # >>>>>>>>>> NOTE END <<<<<<<<<<
 
-# -- Path setup --------------------------------------------------------------
-
-__location__ = os.path.dirname(__file__)
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-# Seems to be not necessary at the moment
-# sys.path.insert(0, os.path.join(__location__, "../examples"))
-
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -66,48 +53,6 @@
 author = "Merck KGaA, Darmstadt, Germany"
 
 
-# -- Run sphinx-apidoc -------------------------------------------------------
-# This hack is necessary since RTD does not issue `sphinx-apidoc` before running
-# `sphinx-build -b html . _build/html`. See Issue:
-# https://github.com/readthedocs/readthedocs.org/issues/1139
-# DON'T FORGET: Check the box "Install your project inside a virtualenv using
-# setup.py install" in the RTD Advanced Settings.
-# Additionally it helps us to avoid running apidoc manually
-
-try:  # for Sphinx >= 1.7
-    from sphinx.ext import apidoc
-except ImportError:
-    from sphinx import apidoc
-
-output_dir = os.path.join(__location__, "sdk")
-baybe_module_dir = os.path.join(__location__, "../baybe")
-try:
-    shutil.rmtree(output_dir)
-except FileNotFoundError:
-    pass
-
-try:
-    args = [
-        "--implicit-namespaces",
-        "-M",
-        "-T",
-        "-e",
-        "-f",
-        "-o",
-        output_dir,
-    ]
-
-    apidoc.main(
-        [
-            *args,
-            baybe_module_dir,
-            baybe_module_dir + "/__init__.py",
-        ]
-    )
-except Exception as e:
-    print(f"Running `sphinx-apidoc` failed!\n{e}")
-
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -139,7 +84,6 @@
 templates_path = ["templates"]
 # Tell sphinx which files should be excluded
 exclude_patterns = ["sdk", "AGENTS.md", "CLAUDE.md", "**/AGENTS.md", "**/CLAUDE.md"]
-autodoc_exclude_modules = ["baybe.utils.clustering_algorithms.third_party.kmedoids"]
 
 # Enable markdown
 # Note that we do not need additional configuration here.
@@ -151,27 +95,59 @@
 # Here, we define regex expressions for errors produced by nitpick that we want to
 # ignore.
 nitpick_ignore_regex = [
-    # Ignore everything that does not include baybe
-    (r"py:.*", r"^(?!.*baybe).*"),
-    # Ignore errors that are from inherited classes we cannot control
+    ##### External package references #####
+    # Qualified references to external packages whose internal module paths cannot be
+    # resolved via intersphinx (e.g. pandas.core.frame.DataFrame vs pandas.DataFrame).
+    (
+        r"py:.*",
+        r"(pandas|numpy|torch|botorch|gpytorch|scipy|sklearn|pathlib|polars|attr|joblib|matplotlib|skfp|rdkit|shap|xyzpy|typing)[\._].*",
+    ),  # noqa: E501
+    ##### Inherited torch.nn.Module docstring references #####
+    # Unqualified names from inherited external docstrings (torch, botorch, sklearn)
+    # that cannot be resolved outside their original documentation context.
+    (r"py:class", r"^(Tensor|Module|Parameter|Dropout|BatchNorm)$"),
+    (r"py:class", r"^(Posterior|MetadataRequest|Ignored)$"),
+    (r"py:attr", r"^(persistent|grad_input|grad_output|requires_grad)$"),
+    (r"py:attr", r"^(device|dtype|dst_type|non_blocking)$"),
+    (r"py:func", r"^(register_module_forward_hook|register_module_forward_pre_hook)$"),
+    (r"py:func", r"^(register_module_full_backward_hook)$"),
+    (r"py:func", r"^(register_module_full_backward_pre_hook|load_state_dict)$"),
+    (r"py:meth", r"^nn\.Module\.load_state_dict$"),
+    ##### Inherited sklearn/scipy docstring artifacts #####
+    # sklearn docstrings use informal type descriptions that Sphinx parses as refs.
+    (r"py:class", r"^(optional|shape|shape=|n_samples|n_features|n_query)$"),
+    (r"py:class", r"^(n_features_new|n_outputs|n_indexed|n_clusters)$"),
+    (r"py:class", r"^(array-like|ndarray|ndarray array|string)$"),
+    (r"py:class", r"^(estimator instance|sparse matrix\})$"),
+    (r"py:class", r"^(\{array-like|default=.*|\{\"default\")$"),
+    (r"py:class", r"^(dtype=np\.int64|if metric == 'precomputed')$"),
+    ##### Type aliases in TYPE_CHECKING blocks #####
+    # These exist only at type-checking time and cannot be resolved by Sphinx.
+    (r"py:class", r"^(GPComponent|TensorCallable|ConvertibleToFloat)$"),
+    (r"py:class", r"^(GPyTorchKernel|GPyTorchLikelihood|GPyTorchMean|GPyTorchModel)$"),
+    (r"py:class", r"^(pd\.DataFrame|pl\.Expr)$"),
+    (r"py:class", r"^(TypeAliasForwardRef|P)$"),
+    (r"py:class", r"^\"(pandas|polars)\"\}?$"),
+    ##### BayBE-specific suppressions #####
+    # Inherited classes we cannot control
     (r"py:.*", r".*DTypeFloatONNX.*"),
-    # Ignore the functions that we manually delete from in child classes
+    # Serialization functions manually deleted from child classes
     (r"py:.*", r".*from_dict.*"),
     (r"py:.*", r".*from_json.*"),
     (r"py:.*", r".*to_dict.*"),
     (r"py:.*", r".*to_json.*"),
     (r"py:.*", r".*_T.*"),
-    # Ignore files for which no __init__ is available at all
+    # Classes for which no __init__ is available at all
     (r"py:.*", "baybe.constraints.conditions.Condition.__init__"),
     (r"py:.*", "baybe.serialization.mixin.SerialMixin.__init__"),
     (r"DeprecationWarning:", ""),
-    # Ignore the generics/aliases
+    # Generics/aliases
     (r"py:class", "baybe.utils.basic._C"),
     (r"py:class", "baybe.utils.basic._T"),
     (r"py:class", "baybe.utils.basic._U"),
     (r"py:class", "baybe.surrogates.composite._SurrogateGetter"),
     (r"ref:obj", "baybe.surrogates.base.ModelContext"),
-    # Ignore custom class properties
+    # Custom class properties
     (r"py:obj", "baybe.settings._AdoptedRandomSeed.*"),
     (r"py:obj", "baybe.acquisition.acqfs.*.supports_batching"),
     (r"py:obj", "baybe.acquisition.acqfs.*.supports_pending_experiments"),
@@ -208,8 +184,15 @@
 ]
 
 
-# Ignore the warnings that are given by autosectionlabel
-suppress_warnings = ["autosectionlabel.*"]
+# Ignore certain warning categories
+suppress_warnings = [
+    "autosectionlabel.*",
+    # Forward reference and guarded import warnings from sphinx-autodoc-typehints.
+    # These are unavoidable since heavy deps (torch, botorch, gpytorch) are lazy-loaded
+    # and only available in TYPE_CHECKING blocks at runtime.
+    "sphinx_autodoc_typehints.forward_reference",
+    "sphinx_autodoc_typehints.guarded_import",
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/index.md

@@ -23,16 +23,6 @@ FAQ <faq>
 :relative-docs: docs/
 ```
 
-```{eval-rst}
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-module-template.rst
-   :recursive:
-   :hidden:
-
-   baybe
-```
-
 ```{toctree}
 :maxdepth: 2
 :titlesonly: