docs: overhaul nitpick-ignore rules and fix broken cross-references

baybe/recommenders/meta/base.py

@@ -52,8 +52,9 @@ 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
-        non-meta recommender is encountered, which is then returned.
+        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

@@ -42,10 +42,12 @@ 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
+        :class:`~baybe.utils.interval.Interval` under a certain (assumed
+        continuous) :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 +58,11 @@ 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`).

baybe/utils/clustering_algorithms/third_party/kmedoids.py

@@ -101,8 +101,8 @@ class KMedoids(BaseEstimator, ClusterMixin, TransformerMixin):
 
     Attributes:
         cluster_centers_ : array, shape = (n_clusters, n_features)
-                or None if metric == 'precomputed'
             Cluster centers, i.e. medoids (elements from the original dataset)
+            or None if metric == 'precomputed'.
 
         medoid_indices_ : array, shape = (n_clusters,)
             The indices of the medoid rows in X

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

@@ -149,29 +149,63 @@
 source_suffix = [".rst", ".md"]
 
 # Here, we define regex expressions for errors produced by nitpick that we want to
-# ignore.
+# ignore. The patterns are organized by category. IMPORTANT: Do NOT add catch-all
+# patterns that suppress all non-baybe references, as this hides broken internal
+# cross-references (see https://github.com/AVHopp/orga/issues/66).
 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 +242,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

@@ -28,7 +28,6 @@ FAQ <faq>
    :toctree: _autosummary
    :template: custom-module-template.rst
    :recursive:
-   :hidden:
 
    baybe
 ```