Merge pull request #257 from IFCA/fix-doc-api-utils

Fix documentation API utils section

Author: Jaime Céspedes Sisniega

docs/source/api_reference/utils.md

@@ -1,54 +1,12 @@
 # Utils
 
-```{eval-rst}
-.. automodule:: frouros.utils
-    :no-members:
-    :no-inherited-members:
-```
+The {mod}`frouros.utils` module contains auxiliary classes, functions or exceptions.
 
-```{currentmodule} frouros.utils
-```
+```{toctree}
+:maxdepth: 2
 
-## Data structures
-
-```{eval-rst}
-.. automodule:: frouros.utils.data_structures
-    :no-members:
-    :no-inherited-members:
-```
-
-```{eval-rst}
-.. autosummary::
-    :toctree: auto_generated/
-    :template: class.md
-
-    EmptyQueueError
-    CircularQueue
-    AccuracyQueue
-```
-
-## Stats
-
-```{eval-rst}
-.. automodule:: frouros.utils.stats
-    :no-members:
-    :no-inherited-members:
-```
-
-```{eval-rst}
-.. autosummary::
-    :toctree: auto_generated/
-    :template: class.md
-
-    IncrementalStat
-    Mean
-    EWMA
-```
-
-```{eval-rst}
-.. autosummary::
-    :toctree: auto_generated/
-    :template: function.md
-
-    permutation
+utils/checks
+utils/data_structures
+utils/kernels
+utils/stats
 ```

docs/source/api_reference/utils/checks.md

@@ -0,0 +1,9 @@
+# Checks
+
+The {mod}`frouros.utils.checks` module contains auxiliary checks functions.
+
+```{eval-rst}
+.. automodule:: frouros.utils.checks
+    :members:
+    :no-inherited-members:
+```

docs/source/api_reference/utils/data_structures.md

@@ -0,0 +1,9 @@
+# Data Structures
+
+The {mod}`frouros.utils.data_structures` module contains auxiliary data structures classes or exceptions.
+
+```{eval-rst}
+.. automodule:: frouros.utils.data_structures
+    :members:
+    :no-inherited-members:
+```

docs/source/api_reference/utils/kernels.md

@@ -0,0 +1,9 @@
+# Kernels
+
+The {mod}`frouros.utils.kernels` module contains auxiliary kernel functions.
+
+```{eval-rst}
+.. automodule:: frouros.utils.kernels
+    :members:
+    :no-inherited-members:
+```

docs/source/api_reference/utils/stats.md

@@ -0,0 +1,9 @@
+# Stats
+
+The {mod}`frouros.utils.stats` module contains auxiliary stats classes or exceptions.
+
+```{eval-rst}
+.. automodule:: frouros.utils.stats
+    :members:
+    :no-inherited-members:
+```

frouros/detectors/data_drift/batch/distance_based/mmd.py

@@ -19,7 +19,7 @@
 class MMD(BaseDistanceBased):
     """MMD (Maximum Mean Discrepancy) [gretton2012kernel]_ detector.
 
-    :param kernel: kernel function, defaults to rbf_kernel
+    :param kernel: kernel function, defaults to :func:`rbf_kernel() <frouros.utils.kernels.rbf_kernel>`
     :type kernel: Callable
     :param chunk_size: chunk size value, defaults to None
     :type chunk_size: Optional[int]
@@ -45,7 +45,7 @@ class MMD(BaseDistanceBased):
     >>> _ = detector.fit(X=X)
     >>> detector.compare(X=Y)[0]
     DistanceResult(distance=0.02146955300299802)
-    """
+    """  # noqa: E501  # pylint: disable=line-too-long
 
     def __init__(  # noqa: D107
         self,

frouros/detectors/data_drift/streaming/distance_based/mmd.py

@@ -20,7 +20,7 @@ class MMD(BaseDistanceBased):
 
     :param window_size: window size value
     :type window_size: int
-    :param kernel: kernel function, defaults to rbf_kernel
+    :param kernel: kernel function, defaults to :func:`rbf_kernel() <frouros.utils.kernels.rbf_kernel>`
     :type kernel: Callable
     :param chunk_size: chunk size value, defaults to None
     :type chunk_size: Optional[int]
@@ -49,7 +49,7 @@ class MMD(BaseDistanceBased):
     ...     distance, _ = detector.update(value=sample)
     ...     if distance is not None:
     ...         print(distance)
-    """
+    """  # noqa: E501  # pylint: disable=line-too-long
 
     def __init__(  # noqa: D107
         self,

frouros/utils/checks.py

@@ -5,7 +5,10 @@
 from frouros.callbacks.base import BaseCallback
 
 
-def check_callbacks(callbacks: Any, expected_cls: BaseCallback) -> None:
+def check_callbacks(
+    callbacks: Any,
+    expected_cls: BaseCallback,
+) -> None:
     """Check callbacks.
 
     :param callbacks: callbacks

frouros/utils/data_structures.py

@@ -1,31 +1,45 @@
 """Data structures module."""
 
-from typing import Any, Optional, List, Union
+from typing import Any, Optional, List, Union, Dict, Tuple
 
 import numpy as np  # type: ignore
 
 
 class EmptyQueueError(Exception):
-    """Empty queue exception."""
-
-    def __init__(self, *args, msg="Queue is empty.", **kwargs) -> None:
-        """Init method.
-
-        :param msg: exception message
-        :type msg: str
-        """
-        super().__init__(msg, *args, **kwargs)
+    """Empty queue exception.
+
+    :param args: exception arguments
+    :type args: Tuple[Any, ...]
+    :param msg: exception message, defaults to "Queue is empty."
+    :type msg: str
+    :param kwargs: exception keyword arguments
+    :type kwargs: Dict[str, Dict[str, Any]]
+    """
+
+    def __init__(  # noqa: D107
+        self,
+        *args: Tuple[Any, ...],
+        msg: str = "Queue is empty.",
+        **kwargs: Dict[str, Dict[str, Any]],
+    ) -> None:
+        super().__init__(
+            msg,
+            *args,
+            **kwargs,
+        )
 
 
 class CircularQueue:
-    """Class representing a circular queue."""
+    """Class representing a circular queue.
 
-    def __init__(self, max_len: int) -> None:
-        """Init method.
+    :param max_len: maximum capacity
+    :type max_len: int
+    """
 
-        :param max_len: maximum capacity
-        :type max_len: int
-        """
+    def __init__(  # noqa: D107
+        self,
+        max_len: int,
+    ) -> None:
         self.count = 0
         self.first = 0
         self.last = -1
@@ -218,14 +232,16 @@ def __getitem__(self, idx: int) -> Any:
 
 
 class AccuracyQueue(CircularQueue):
-    """Class representing an accuracy queue."""
+    """Class representing an accuracy queue.
 
-    def __init__(self, max_len: int) -> None:
-        """Init method.
+    :param max_len: maximum capacity
+    :type max_len: int
+    """
 
-        :param max_len: maximum capacity
-        :type max_len: int
-        """
+    def __init__(  # noqa: D107
+        self,
+        max_len: int,
+    ) -> None:
         super().__init__(max_len=max_len)
         self.num_true = 0
 

frouros/utils/stats.py

@@ -36,8 +36,9 @@ def get(self) -> float:
 class Mean(IncrementalStat):
     """Incremental mean class."""
 
-    def __init__(self) -> None:
-        """Init method."""
+    def __init__(  # noqa: D107
+        self,
+    ) -> None:
         self.mean = 0.0
         self.num_values = 0
 
@@ -111,10 +112,16 @@ def get(self) -> float:
 
 
 class CircularMean(Mean):
-    """Circular mean class."""
+    """Circular mean class.
 
-    def __init__(self, size: int) -> None:
-        """Init method."""
+    :param size: size of the circular mean
+    :type size: int
+    """
+
+    def __init__(  # noqa: D107
+        self,
+        size: int,
+    ) -> None:
         super().__init__()
         self.queue = CircularQueue(max_len=size)
 
@@ -137,14 +144,16 @@ def update(self, value: Union[int, float]) -> None:
 
 
 class EWMA(IncrementalStat):
-    """EWMA (Exponential Weighted Moving Average) class."""
+    """EWMA (Exponential Weighted Moving Average) class.
 
-    def __init__(self, alpha: float) -> None:
-        """Init method.
+    :param alpha: alpha value
+    :type alpha: float
+    """
 
-        :param alpha:
-        :type alpha: float
-        """
+    def __init__(  # noqa: D107
+        self,
+        alpha: float,
+    ) -> None:
         self.alpha = alpha
         self.one_minus_alpha = 1.0 - self.alpha
         self.mean = 0
@@ -228,9 +237,9 @@ def permutation(  # pylint: disable=too-many-arguments,too-many-locals
     :type num_permutations: int
     :param num_jobs: number of jobs to use
     :type num_jobs: int
-    :param random_state: random state value
+    :param random_state: random state value, defaults to None
     :type random_state: Optional[int]
-    :param verbose: verbose flag
+    :param verbose: verbose flag, defaults to False
     :type verbose: bool
     :return: permuted statistics
     :rtype: List[float]