diff --git a/baybe/recommenders/meta/base.py b/baybe/recommenders/meta/base.py index 21b0758843..b6c439345b 100644 --- a/baybe/recommenders/meta/base.py +++ b/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. diff --git a/baybe/surrogates/gaussian_process/core.py b/baybe/surrogates/gaussian_process/core.py index 81d7f00c26..dba9ba1cec 100644 --- a/baybe/surrogates/gaussian_process/core.py +++ b/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 diff --git a/baybe/transformations/base.py b/baybe/transformations/base.py index 4b84620980..4ed9e6f932 100644 --- a/baybe/transformations/base.py +++ b/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 `_, 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 `_, 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`). diff --git a/baybe/utils/clustering_algorithms/third_party/kmedoids.py b/baybe/utils/clustering_algorithms/third_party/kmedoids.py index 5f894cc1e5..33c18ac5e6 100644 --- a/baybe/utils/clustering_algorithms/third_party/kmedoids.py +++ b/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 diff --git a/docs/components/transformations.md b/docs/components/transformations.md index 5e349cc971..59c3fc0e81 100644 --- a/docs/components/transformations.md +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index aa0078b88a..0d0cddeb09 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.md b/docs/index.md index 2e94cc9a3b..dbf0348786 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,6 @@ FAQ :toctree: _autosummary :template: custom-module-template.rst :recursive: - :hidden: baybe ```