Remove :meta private: from documentation so Sphinx doesn't hide subclasses (#2437)

esantorella · facebook-github-bot · commit b24b3f14161f · 2024-07-21T16:04:27.000-07:00
Summary: ## Motivation * Addresses #2419 , classes missing from Sphinx-rendered API documentation * Makes ABCs that were previously manually hidden (by me) show up in the documentation. I now think it was a mistake to hide these, as users frequently need to use these. # Changes in this PR * Remove `:meta private:` from docstrings. `:meta_private` was present in many ABCs; it prevents them from appearing in the Sphinx-rendered API documentation. It also seems to prevent their subclasses from appearing if the subclasses don't "override" the docstring. * Fixed up a docstring in `batch_cross_validation` * Removed ABC `HomotopySchedule`, which only had one subclass. We might want to consider adding a lint to check that `:meta private:` is not added again, but I don't expect it to come up too often. Pull Request resolved: #2437 Test Plan: Built the website locally and confirmed that the documentation looks okay and that formerly missing classes such as `qLogNoisyExpectedHypervolumeImprovement` and `AffineInputTransform` now show up. Reviewed By: saitcakmak Differential Revision: D60020672 Pulled By: esantorella fbshipit-source-id: 3f546dba4404fc9303a2b43f71c9dab5c30d3822
diff --git a/botorch/acquisition/acquisition.py b/botorch/acquisition/acquisition.py
@@ -28,8 +28,6 @@ class AcquisitionFunction(Module, ABC):
     Please note that if your acquisition requires a backwards call,
     you will need to wrap the backwards call inside of an enable_grad
     context to be able to optimize the acquisition. See #1164.
-
-    :meta private:
     """
 
     _log: bool = False  # whether the acquisition utilities are in log-space
@@ -79,8 +77,6 @@ def forward(self, X: Tensor) -> Tensor:
 class OneShotAcquisitionFunction(AcquisitionFunction, ABC):
     r"""
     Abstract base class for acquisition functions using one-shot optimization
-
-    :meta private:
     """
 
     @abstractmethod
@@ -115,8 +111,6 @@ class MCSamplerMixin(ABC):
 
     Attributes:
         _default_sample_shape: The `sample_shape` for the default sampler.
-
-    :meta private:
     """
 
     _default_sample_shape = torch.Size([512])
@@ -169,8 +163,6 @@ class MultiModelAcquisitionFunction(AcquisitionFunction, ABC):
     This is currently only a placeholder to help with some development
     in Ax. We plan to add some acquisition functions utilizing multiple
     models in the future.
-
-    :meta private:
     """
 
     def __init__(self, model_dict: ModelDict) -> None:
diff --git a/botorch/acquisition/analytic.py b/botorch/acquisition/analytic.py
@@ -49,11 +49,7 @@
 
 
 class AnalyticAcquisitionFunction(AcquisitionFunction, ABC):
-    r"""
-    Base class for analytic acquisition functions.
-
-    :meta private:
-    """
+    """Base class for analytic acquisition functions."""
 
     def __init__(
         self,
diff --git a/botorch/acquisition/cached_cholesky.py b/botorch/acquisition/cached_cholesky.py
@@ -66,8 +66,6 @@ class CachedCholeskyMCSamplerMixin(MCSamplerMixin):
     Specifically, this is for acquisition functions that require sampling from
     the posterior P(f(X_baseline, X) | D). The Cholesky of the posterior
     covariance over f(X_baseline) is cached.
-
-    :meta private:
     """
 
     def __init__(
diff --git a/botorch/acquisition/cost_aware.py b/botorch/acquisition/cost_aware.py
@@ -31,11 +31,7 @@
 
 
 class CostAwareUtility(Module, ABC):
-    r"""
-    Abstract base class for cost-aware utilities.
-
-    :meta private:
-    """
+    """Abstract base class for cost-aware utilities."""
 
     @abstractmethod
     def forward(
@@ -55,7 +51,6 @@ def forward(
         Returns:
             A `num_fantasies x batch_shape`-dim Tensor of cost-transformed utilities.
         """
-        pass  # pragma: no cover
 
 
 class GenericCostAwareUtility(CostAwareUtility):
diff --git a/botorch/acquisition/logei.py b/botorch/acquisition/logei.py
@@ -71,8 +71,6 @@
 class LogImprovementMCAcquisitionFunction(SampleReducingMCAcquisitionFunction):
     r"""
     Abstract base class for Monte-Carlo-based batch LogEI acquisition functions.
-
-    :meta private:
     """
 
     _log: bool = True
diff --git a/botorch/acquisition/max_value_entropy_search.py b/botorch/acquisition/max_value_entropy_search.py
@@ -65,8 +65,6 @@ class MaxValueBase(AcquisitionFunction, ABC):
 
     Subclasses need to implement `_sample_max_values` and _compute_information_gain`
     methods.
-
-    :meta private:
     """
 
     def __init__(
diff --git a/botorch/acquisition/monte_carlo.py b/botorch/acquisition/monte_carlo.py
@@ -58,8 +58,6 @@
 class MCAcquisitionFunction(AcquisitionFunction, MCSamplerMixin, ABC):
     r"""
     Abstract base class for Monte-Carlo based batch acquisition functions.
-
-    :meta private:
     """
 
     def __init__(
diff --git a/botorch/acquisition/multi_objective/multi_output_risk_measures.py b/botorch/acquisition/multi_objective/multi_output_risk_measures.py
@@ -55,8 +55,6 @@ class MultiOutputRiskMeasureMCObjective(
     If the q-batch includes samples corresponding to multiple inputs, it is assumed
     that first `n_w` samples correspond to first input, second `n_w` samples
     correspond to second input, etc.
-
-    :meta private:
     """
 
     def __init__(
diff --git a/botorch/acquisition/multi_objective/objective.py b/botorch/acquisition/multi_objective/objective.py
@@ -150,7 +150,7 @@ def __init__(
         constraint_idcs: List[int],
         objective: Optional[MCMultiOutputObjective] = None,
     ) -> None:
-        r"""Construct a feasibility weighted objective.
+        r"""Construct a feasibility-weighted objective.
 
         This applies feasibility weighting before calculating the objective value.
         Defaults to identity if no constraints or objective is present.
diff --git a/botorch/acquisition/objective.py b/botorch/acquisition/objective.py
@@ -32,11 +32,7 @@
 
 
 class PosteriorTransform(Module, ABC):
-    r"""
-    Abstract base class for objectives that transform the posterior.
-
-    :meta private:
-    """
+    """Abstract base class for objectives that transform the posterior."""
 
     @abstractmethod
     def evaluate(self, Y: Tensor) -> Tensor:
@@ -240,8 +236,6 @@ class MCAcquisitionObjective(Module, ABC):
         _verify_output_shape: If True and `X` is given, check that the q-batch
             shape of the objectives agrees with that of X.
         _is_mo: A boolean denoting whether the objectives are multi-output.
-
-    :meta private:
     """
 
     _verify_output_shape: bool = True
diff --git a/botorch/acquisition/risk_measures.py b/botorch/acquisition/risk_measures.py
@@ -44,8 +44,6 @@ class RiskMeasureMCObjective(MCAcquisitionObjective, ABC):
     is to calculate the risk measures w.r.t. the lower tail of the distribution.
     This can be changed by passing a preprocessing function with
     `weights=torch.tensor([-1.0])`.
-
-    :meta private:
     """
 
     def __init__(
diff --git a/botorch/cross_validation.py b/botorch/cross_validation.py
@@ -114,7 +114,10 @@ def batch_cross_validation(
     observation_noise: bool = False,
     model_init_kwargs: Optional[Dict[str, Any]] = None,
 ) -> CVResults:
-    r"""Perform cross validation by using gpytorch batch mode.
+    r"""Perform cross validation by using GPyTorch batch mode.
+
+    WARNING: This function is currently very memory inefficient; use it only
+        for problems of small size.
 
     Args:
         model_cls: A GPyTorchModel class. This class must initialize the likelihood
@@ -138,6 +141,7 @@ def batch_cross_validation(
         >>> import torch
         >>> from botorch.cross_validation import (
         ...     batch_cross_validation, gen_loo_cv_folds
+        ... )
         >>>
         >>> from botorch.models import SingleTaskGP
         >>> from botorch.models.transforms.input import Normalize
@@ -148,7 +152,7 @@ def batch_cross_validation(
         >>> train_Y = torch.rand_like(train_X)
         >>> cv_folds = gen_loo_cv_folds(train_X, train_Y)
         >>> input_transform = Normalize(d=train_X.shape[-1])
-        >>> output_transform = Standardize(
+        >>> outcome_transform = Standardize(
         ...     m=train_Y.shape[-1], batch_shape=cv_folds.train_Y.shape[:-2]
         ... )
         >>>
@@ -158,12 +162,9 @@ def batch_cross_validation(
         ...    cv_folds=cv_folds,
         ...    model_init_kwargs={
         ...        "input_transform": input_transform,
-        ...        "output_transform": output_transform,
+        ...        "outcome_transform": outcome_transform,
         ...    },
         ... )
-
-    WARNING: This function is currently very memory inefficient, use it only
-        for problems of small size.
     """
     model_init_kws = model_init_kwargs if model_init_kwargs is not None else {}
     if cv_folds.train_Yvar is not None:
diff --git a/botorch/generation/sampling.py b/botorch/generation/sampling.py
@@ -38,11 +38,7 @@
 
 
 class SamplingStrategy(Module, ABC):
-    r"""
-    Abstract base class for sampling-based generation strategies.
-
-    :meta private:
-    """
+    """Abstract base class for sampling-based generation strategies."""
 
     @abstractmethod
     def forward(self, X: Tensor, num_samples: int = 1) -> Tensor:
diff --git a/botorch/models/deterministic.py b/botorch/models/deterministic.py
@@ -36,11 +36,7 @@
 
 
 class DeterministicModel(EnsembleModel):
-    r"""
-    Abstract base class for deterministic models.
-
-    :meta private:
-    """
+    """Abstract base class for deterministic models."""
 
     @abstractmethod
     def forward(self, X: Tensor) -> Tensor:
diff --git a/botorch/models/ensemble.py b/botorch/models/ensemble.py
@@ -22,11 +22,7 @@
 
 
 class EnsembleModel(Model, ABC):
-    r"""
-    Abstract base class for ensemble models.
-
-    :meta private:
-    """
+    """Abstract base class for ensemble models."""
 
     @abstractmethod
     def forward(self, X: Tensor) -> Tensor:
diff --git a/botorch/models/fully_bayesian.py b/botorch/models/fully_bayesian.py
@@ -108,8 +108,6 @@ class PyroModel:
     The utility of `PyroModel` is in enabling fast fitting with NUTS, since we
     would otherwise need to use GPyTorch, which is computationally infeasible
     in combination with Pyro.
-
-    :meta private:
     """
 
     def set_inputs(
diff --git a/botorch/models/gpytorch.py b/botorch/models/gpytorch.py
@@ -60,8 +60,6 @@ class GPyTorchModel(Model, ABC):
 
     The easiest way to use this is to subclass a model from a GPyTorch model
     class (e.g. an `ExactGP`) and this `GPyTorchModel`. See e.g. `SingleTaskGP`.
-
-    :meta private:
     """
 
     likelihood: Likelihood
@@ -269,8 +267,6 @@ class BatchedMultiOutputGPyTorchModel(GPyTorchModel):
 
     This model should be used when the same training data is used for all outputs.
     Outputs are modeled independently by using a different batch for each output.
-
-    :meta private:
     """
 
     _num_outputs: int
@@ -603,8 +599,6 @@ class ModelListGPyTorchModel(ModelList, GPyTorchModel, ABC):
     This is meant to be used with a gpytorch ModelList wrapper for independent
     evaluation of submodels. Those submodels can themselves be multi-output
     models, in which case the task covariances will be ignored.
-
-    :meta private:
     """
 
     @property
@@ -740,8 +734,6 @@ class MultiTaskGPyTorchModel(GPyTorchModel, ABC):
 
     This class provides the `posterior` method to models that implement a
     "long-format" multi-task GP in the style of `MultiTaskGP`.
-
-    :meta private:
     """
 
     def _map_tasks(self, task_values: Tensor) -> Tensor:
diff --git a/botorch/models/likelihoods/pairwise.py b/botorch/models/likelihoods/pairwise.py
@@ -28,8 +28,6 @@
 class PairwiseLikelihood(Likelihood, ABC):
     """
     Pairwise likelihood base class for pairwise preference GP (e.g., PairwiseGP).
-
-    :meta private:
     """
 
     def __init__(self, max_plate_nesting: int = 1):
diff --git a/botorch/models/transforms/input.py b/botorch/models/transforms/input.py
@@ -52,8 +52,6 @@ class InputTransform(ABC):
             transform in eval() mode.
         transform_on_fantasize: A boolean indicating whether to apply
             the transform when called from within a `fantasize` call.
-
-    :meta private:
     """
 
     is_one_to_many: bool = False
@@ -256,8 +254,6 @@ class ReversibleInputTransform(InputTransform, ABC):
     Properties:
         reverse: A boolean indicating if the functionality of transform
             and untransform methods should be swapped.
-
-    :meta private:
     """
 
     reverse: bool
diff --git a/botorch/models/transforms/outcome.py b/botorch/models/transforms/outcome.py
@@ -39,11 +39,7 @@
 
 
 class OutcomeTransform(Module, ABC):
-    r"""
-    Abstract base class for outcome transforms.
-
-    :meta private:
-    """
+    """Abstract base class for outcome transforms."""
 
     @abstractmethod
     def forward(
diff --git a/botorch/optim/homotopy.py b/botorch/optim/homotopy.py
@@ -6,44 +6,18 @@
 from __future__ import annotations
 
 import math
-from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Any, Callable, List, Optional, Union
+from typing import Callable, List, Optional, Union
 
 import torch
 from torch import Tensor
 from torch.nn import Parameter
 
 
-class HomotopySchedule(ABC):
-    @property
-    @abstractmethod
-    def num_steps(self) -> int:
-        """Number of steps in the schedule."""
-
-    @property
-    @abstractmethod
-    def value(self) -> Any:
-        """Current value in the schedule."""
-
-    @property
-    @abstractmethod
-    def should_stop(self) -> bool:
-        """Return true if we have incremented past the end of the schedule."""
-
-    @abstractmethod
-    def restart(self) -> None:
-        """Restart the schedule to start from the beginning."""
-
-    @abstractmethod
-    def step(self) -> None:
-        """Move to solving the next problem."""
-
-
-class FixedHomotopySchedule(HomotopySchedule):
+class FixedHomotopySchedule:
     """Homotopy schedule with a fixed list of values."""
 
-    def __init__(self, values: List[Any]) -> None:
+    def __init__(self, values: List[float]) -> None:
         r"""Initialize FixedHomotopySchedule.
 
         Args:
@@ -57,7 +31,7 @@ def num_steps(self) -> int:
         return len(self._values)
 
     @property
-    def value(self) -> Any:
+    def value(self) -> float:
         return self._values[self.idx]
 
     @property
@@ -114,7 +88,7 @@ class HomotopyParameter:
     """
 
     parameter: Union[Parameter, Tensor]
-    schedule: HomotopySchedule
+    schedule: FixedHomotopySchedule
 
 
 class Homotopy:
diff --git a/botorch/optim/stopping.py b/botorch/optim/stopping.py
@@ -17,8 +17,6 @@ class StoppingCriterion(ABC):
 
     Stopping criteria are implemented as a objects rather than a function, so that they
     can keep track of past function values between optimization steps.
-
-    :meta private:
     """
 
     @abstractmethod
diff --git a/botorch/posteriors/posterior.py b/botorch/posteriors/posterior.py
diff --git a/botorch/sampling/base.py b/botorch/sampling/base.py
diff --git a/botorch/utils/containers.py b/botorch/utils/containers.py
diff --git a/botorch/utils/multi_objective/box_decompositions/box_decomposition.py b/botorch/utils/multi_objective/box_decompositions/box_decomposition.py
diff --git a/botorch/utils/sampling.py b/botorch/utils/sampling.py
