Enhance documentation standards and improve docstring formats across multiple files

Author: Weslley da Silva Pereira

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
       - id: check-merge-conflict
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.4
+    rev: v0.12.7
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

CONTRIBUTING.md

@@ -50,3 +50,135 @@ __authors__ = ["Your Name"]
 ```
 
 For files based on existing algorithms from academic papers, include the original authors in the `__credits__` variable at [soogo/\_\_init\_\_.py](soogo/__init__.py).
+
+## Documentation standards
+
+### Docstring format
+
+This project uses **Sphinx-style** docstrings with reStructuredText (reST) markup. All public modules, classes, methods, and functions must have docstrings.
+
+#### Module docstrings
+
+Every Python module should start with a brief one-line description:
+
+```python
+"""Brief description of the module."""
+```
+
+#### Class docstrings
+
+Classes should document their purpose, attributes, and parameters:
+
+```python
+class MyClass:
+    """Brief one-line description.
+
+    Longer description if needed. Can span multiple paragraphs.
+
+    :param param1: Description of param1.
+    :param param2: Description of param2.
+
+    .. attribute:: attr1
+
+        Description of attribute attr1.
+
+    .. attribute:: attr2
+
+        Description of attribute attr2.
+
+    References
+    ----------
+    .. [#] Author. Title. Journal, Year. DOI or URL.
+    """
+```
+
+#### Function docstrings
+
+Functions should document parameters, return values, and include examples when helpful:
+
+```python
+def my_function(x, y, *, option=None):
+    """Brief one-line description.
+
+    Longer description if needed. Explain what the function does,
+    any important algorithms, or behaviors.
+
+    :param x: Description of parameter x.
+    :param y: Description of parameter y.
+    :param option: Description of optional keyword argument.
+        The default is None.
+    :return: Description of return value.
+
+    References
+    ----------
+    .. [#] Author. Title. Journal, Year. DOI or URL.
+    """
+```
+
+#### Key formatting rules
+
+- **Line length**: Docstrings must not exceed 80 characters per line (enforced by Ruff W505)
+- **Parameters**: Use `:param name: description` format
+- **Return values**: Use `:return: description` format
+- **Types**: Can be included inline with params (e.g., `:param int maxeval:`) or use type hints
+- **Attributes**: Use `.. attribute:: name` followed by indented description
+- **References**: Use numbered footnote style with `.. [#]` for academic citations
+- **Math**: Use inline math with `:math:\`expression\``or display math blocks with`.. math::`
+
+#### Example from the codebase
+
+```python
+def gosac(
+    fun,
+    gfun,
+    bounds,
+    maxeval: int,
+    *,
+    surrogateModel: Optional[Surrogate] = None,
+    disp: bool = False,
+    callback: Optional[Callable[[OptimizeResult], None]] = None,
+):
+    """Minimize a scalar function subject to constraints.
+
+    The surrogate models are used to approximate the constraints. The
+    objective function is assumed to be cheap to evaluate, while the
+    constraints are assumed to be expensive to evaluate.
+
+    This method is based on [#]_.
+
+    :param fun: The objective function to be minimized.
+    :param gfun: The constraint function to be minimized. The
+        constraints must be formulated as g(x) <= 0.
+    :param bounds: List with the limits [x_min,x_max] of each
+        direction x in the search space.
+    :param maxeval: Maximum number of function evaluations.
+    :param surrogateModel: Surrogate model to be used for the
+        constraints. If None is provided, a :class:`RbfModel` model
+        is used.
+    :param disp: If True, print information about the optimization
+        process. The default is False.
+    :param callback: If provided, the callback function will be
+        called after each iteration with the current optimization
+        result. The default is None.
+    :return: The optimization result.
+
+    References
+    ----------
+    .. [#] Juliane Müller and Joshua D. Woodbury. 2017. GOSAC: global
+        optimization with surrogate approximation of constraints.
+        J. of Global Optimization 69, 1 (September 2017), 117–136.
+        https://doi.org/10.1007/s10898-017-0496-y
+    """
+```
+
+### Building documentation
+
+To build the HTML documentation locally:
+
+```bash
+cd docs
+pip install -r requirements.txt
+sphinx-build . _build/html
+```
+
+The generated documentation will be in `docs/_build/html/`.

soogo/acquisition/maximize_distance.py

@@ -64,6 +64,7 @@ def optimize(
         :param n: Number of points to be acquired.
         :param points: Points to consider for distance maximization. If None,
             use all previously sampled points in the surrogate model.
+        :return: Array of acquired points that maximize minimum distance.
         """
         iindex = surrogateModel.iindex
         optimizer = self.optimizer if len(iindex) == 0 else self.mi_optimizer

soogo/acquisition/multiple_acquisition.py

@@ -26,6 +26,17 @@
 
 
 class MultipleAcquisition(Acquisition):
+    r"""Apply multiple acquisition functions sequentially.
+
+    This acquisition function runs multiple acquisition strategies in
+    sequence, filtering candidates to ensure they are far enough apart.
+
+    :param acquisitionFuncArray: Sequence of acquisition functions to
+        apply in order.
+    :param **kwargs: Additional arguments passed to the base Acquisition
+        class.
+    """
+
     def __init__(
         self,
         acquisitionFuncArray: Sequence[Acquisition],

soogo/acquisition/utils.py

@@ -20,7 +20,6 @@
 
 import numpy as np
 from scipy.spatial.distance import cdist
-from scipy.spatial import KDTree
 import networkx as nx
 from networkx.algorithms.approximation import maximum_independent_set
 
@@ -152,13 +151,10 @@ def select_weighted_candidates(
     :param tol: Tolerance value for excluding candidates that are too close to
         current sample points.
     :param weightpattern: List of weights to use cyclically for each selection.
-    :return:
-
-        * n-by-dim matrix with the selected points.
-
-        * n-by-(n+m) matrix with the distances between the n selected points
-            and the (n+m) sampled points (m is the number of points that have
-            been sampled so far).
+    :return: Tuple containing (1) n-by-dim matrix with the selected
+        points, and (2) n-by-(n+m) matrix with the distances between the
+        n selected points and the (n+m) sampled points (m is the number
+        of points that have been sampled so far).
     """
     # Compute neighbor distances
     dist = np.min(distx, axis=1)
@@ -224,15 +220,32 @@ def select_weighted_candidates(
 
 
 class FarEnoughSampleFilter:
-    def __init__(self, X, tol):
-        self.tree = KDTree(X)
-        self.tol = tol
+    """Filter candidate points that are too close to existing points.
+
+    This utility class filters out candidates that are within a minimum
+    distance threshold from already sampled points.
+
+    :param X: Matrix of existing sample points (n x d).
+    :param tol: Minimum distance threshold. Points closer than this are
+        filtered out.
+    """
 
     def is_far_enough(self, x):
+        """Check if a point is far enough from existing samples.
+
+        :param x: Point to check (d-dimensional vector).
+        :return: True if the point is far enough, False otherwise.
+        """
         dist, _ = self.tree.query(x.reshape(1, -1))
         return dist[0] >= self.tol
 
     def __call__(self, Xc):
+        """Filter candidates based on minimum distance criterion.
+
+        :param Xc: Matrix of candidate points (m x d).
+        :return: Filtered matrix containing only points that are far
+            enough from existing samples.
+        """
         # Discard points that are too close to X
         mask0 = np.array([self.is_far_enough(x) for x in Xc], dtype=bool)
         Xc0 = Xc[mask0]

soogo/model/rbf.py

@@ -202,6 +202,14 @@ def reserve(self, maxeval: int, dim: int, ntarget: int = 1) -> None:
             )
 
     def eval_kernel(self, x, y=None):
+        """Evaluate the RBF kernel between points.
+
+        :param x: m-by-d matrix with m point coordinates in a d-dimensional
+            space.
+        :param y: n-by-d matrix with n point coordinates in a d-dimensional
+            space. If None, use x.
+        :return: Kernel matrix (m x n).
+        """
         if y is None:
             y = x
         return self.rbf(cdist(x, y))
@@ -283,9 +291,9 @@ def __call__(
         coef0 = self._coef[0 : self._m]
         coef1 = self._coef[self._m : self._m + self.polynomial_tail_size()]
         if i >= 0:
-            assert (
-                i < self.ntarget
-            ), "Index out of bounds for target dimension."
+            assert i < self.ntarget, (
+                "Index out of bounds for target dimension."
+            )
             if self.ntarget > 1:
                 coef0 = coef0[:, i]
                 coef1 = coef1[:, i]
@@ -525,7 +533,7 @@ def iindex(self) -> tuple[int, ...]:
         """Return iindex, the sequence of integer variable indexes."""
         return self._iindex
 
-    def prepare_mu_measure(self):
+    def prepare_mu_measure(self) -> None:
         """Prepare the model for mu measure computation.
 
         This routine computes the LDLt factorization of the matrix A, which is

soogo/optimize/bayesian_optimization.py

@@ -30,15 +30,15 @@ def bayesian_optimization(
     acquisitionFunc: Optional[MaximizeEI] = None,
     **kwargs,
 ) -> OptimizeResult:
-    """Wrapper for surrogate_optimization() using a Gaussian Process surrogate
+    r"""Wrapper for surrogate_optimization() using a Gaussian Process surrogate
     model and the Expected Improvement acquisition function.
 
-    :param \\*args: Positional arguments passed to surrogate_optimization().
+    :param *args: Positional arguments passed to surrogate_optimization().
     :param surrogateModel: Gaussian Process surrogate model. The
         default is GaussianProcess(). On exit, if provided, the surrogate
         model the points used during the optimization.
     :param acquisitionFunc: Acquisition function to be used.
-    :param \\*\\*kwargs: Keyword arguments passed to surrogate_optimization().
+    :param **kwargs: Keyword arguments passed to surrogate_optimization().
     """
     # Initialize optional variables
     if surrogateModel is None:

soogo/sampling.py

@@ -39,7 +39,13 @@ class SamplingStrategy(Enum):
     MITCHEL91 = 6  #: Cover empty regions in the search space
 
 
-def _slhd_permutation_matrix(m: int, d: int):
+def _slhd_permutation_matrix(m: int, d: int) -> np.ndarray:
+    """Generate permutation matrix for SLHD sampling.
+
+    :param m: Number of samples.
+    :param d: Number of dimensions.
+    :return: m-by-d permutation matrix.
+    """
     # Generate permutation matrix P
     P = np.zeros((m, d), dtype=int)
     P[:, 0] = np.arange(m)

soogo/termination.py

@@ -36,15 +36,14 @@ class TerminationCondition(ABC):
 
     This class defines the interface for conditions that can be used to
     determine when an optimization process should terminate.
-
-    :param out: The optimization result containing the current state.
-    :param model: The surrogate model used in the optimization, if any.
-    :return: True if the condition is met, False otherwise.
     """
 
     @abstractmethod
     def is_met(self) -> bool:
-        """Check if the condition is met."""
+        """Check if the termination condition is met.
+
+        :return: True if the condition is met, False otherwise.
+        """
         pass
 
     @abstractmethod
@@ -104,19 +103,19 @@ def update(
             # No function evaluations, cannot update condition
             return
 
-        assert (
-            out.nobj == 1
-        ), "Expected a single objective function value, but got multiple objectives."
+        assert out.nobj == 1, (
+            "Expected a single objective function value, but got multiple objectives."
+        )
 
         # Get the new best value from the optimization result
         new_best_value = (
             out.fx.flatten()[0].item()
             if isinstance(out.fx, np.ndarray)
             else out.fx
         )
-        assert isinstance(
-            new_best_value, float
-        ), "Expected out.fx to be a float, but got a different type."
+        assert isinstance(new_best_value, float), (
+            "Expected out.fx to be a float, but got a different type."
+        )
 
         # Compute the relative improvement
         value_improvement = self.lowest_value - new_best_value
@@ -148,9 +147,9 @@ def __init__(self, termination: TerminationCondition, period=30) -> None:
         self.history = deque(maxlen=period)
 
     def is_met(self) -> bool:
-        assert isinstance(
-            self.history.maxlen, int
-        ), "History maxlen must be set."
+        assert isinstance(self.history.maxlen, int), (
+            "History maxlen must be set."
+        )
 
         if len(self.history) < self.history.maxlen:
             return False

soogo/utils.py

@@ -36,7 +36,7 @@ def find_pareto_front(fx, iStart: int = 0) -> list:
                 elif all(fx[j] <= fx[i]) and any(fx[j] < fx[i]):
                     # x[j] dominates x[i]
                     # No need to continue checking, otherwise the previous
-                    # iteration was not a balid Pareto front
+                    # iteration was not a valid Pareto front
                     pareto[i] = False
                     break
     return [i for i in range(len(fx)) if pareto[i]]
@@ -49,6 +49,7 @@ def gp_expected_improvement(delta, sigma):
         the current best function value and :math:`\\mu_n(x)` is the expected
         value for :math:`f(x)`.
     :param sigma: The standard deviation :math:`\\sigma_n(x)`.
+    :return: Expected improvement value.
 
     References
     ----------