Update docs

Author: sergeyklay

clusx/__main__.py

@@ -1,8 +1,17 @@
-"""Entry point for direct module execution.
+"""
+Entry point for direct module execution.
 
 This module serves as the main entry point when the package is executed directly
-using ``python -m clusx``. It initializes the command-line interface and passes
-control to the main CLI function.
+using ``python -m clusx``.
+
+It initializes the command-line interface and passes control to the main CLI function.
+
+When executed with ``python -m clusx``, this module will initialize the CLI and
+handle command-line arguments through the main function in the cli module.
+
+See Also
+--------
+clusx.cli : Contains the main CLI implementation
 """
 
 import sys
@@ -11,11 +20,15 @@
 
 
 def init() -> None:
-    """Run clusx.cli.main() when current file is executed by an interpreter.
+    """
+    Run clusx.cli.main() when current file is executed by an interpreter.
+
+    This function ensures that the CLI main function is only executed when this
+    file is run directly, not when imported as a module.
 
-    If the file is used as a module, the :func:`clusx.cli.main` function will
-    not automatically execute. The :func:`sys.exit` function is called with a
-    return value of :func:`clusx.cli.main`, as all good UNIX programs do.
+    The :func:`sys.exit` function is called with the return value of
+    :func:`clusx.cli.main`, following standard UNIX program conventions for exit
+    codes.
     """
     if __name__ == "__main__":
         sys.exit(main())

clusx/clustering/models.py

@@ -10,18 +10,19 @@
 
 Classes
 -------
-DirichletProcess
+:class:`DirichletProcess`
     Implements clustering using the Dirichlet Process with concentration parameter
     alpha and precision parameter kappa.
-PitmanYorProcess
+:class:`PitmanYorProcess`
     Extends DirichletProcess with an additional discount parameter for more flexible
     power-law behavior in cluster size distributions.
 
 Notes
 -----
-Both implementations follow a scikit-learn compatible API with fit(), predict(),
-and fit_predict() methods. The Pitman-Yor Process is generally better suited for
-text data as it can model the power-law distributions common in natural language.
+Both implementations follow a scikit-learn compatible API with ``fit()``,
+``predict()``, and ``fit_predict()`` methods. The Pitman-Yor Process is generally
+better suited for text data as it can model the power-law distributions common in
+natural language.
 """
 
 from __future__ import annotations
@@ -598,7 +599,7 @@ def fit_predict(self, documents, _y=None):
 
         Notes
         -----
-        This method is a convenience function that calls fit() followed by
+        This method is a convenience function that calls :func:`fit` followed by
         returning the cluster labels from the fitting process.
         """
         self.fit(documents)

clusx/errors.py

@@ -10,27 +10,41 @@ class EvaluationError(ClusxError):
 
 
 class ClusterIntegrityError(ClusxError):
-    """Error raised when a cluster assignments file has integrity issues.
+    """
+    Error raised when a cluster assignments file has integrity issues.
 
     This error indicates that the cluster assignments file is corrupted,
     was created with errors, or is missing critical information needed
     for further processing.
+
+    See Also
+    --------
+    :class:`MissingClusterColumnError`, :class:`MissingParametersError`
     """
 
 
 class MissingClusterColumnError(ClusterIntegrityError):
-    """Error raised when a cluster assignments file is missing the cluster column.
+    """
+    Error raised when a cluster assignments file is missing the cluster column.
 
     This error indicates that the file does not contain a column that starts with
     ``Cluster_`` (such as Cluster_PYP or Cluster_DP), which is required for identifying
     cluster assignments.
+
+    See Also
+    --------
+    ClusterIntegrityError : Parent class for integrity errors
+    MissingParametersError : Related error for missing parameters
     """
 
     def __init__(self, file_path: str):
-        """Initialize the error with the path to the problematic file.
+        """
+        Initialize the error with the path to the problematic file.
 
-        Args:
-            file_path: Path to the file missing the cluster column
+        Parameters
+        ----------
+        file_path : str
+            Path to the file missing the cluster column
         """
         self.file_path = file_path
         message = (
@@ -42,18 +56,35 @@ def __init__(self, file_path: str):
 
 
 class MissingParametersError(ClusterIntegrityError):
-    """Error raised when a cluster assignments file is missing required parameters.
+    """
+    Error raised when a cluster assignments file is missing required parameters.
 
     This error indicates that the file is missing one or more of the required
     parameters (alpha, sigma, variance) needed for further processing.
+
+    Parameters
+    ----------
+    file_path : str
+        Path to the file with missing parameters
+    missing_params : list[str]
+        List of parameter names that are missing
+
+    See Also
+    --------
+    ClusterIntegrityError : Parent class for integrity errors
+    MissingClusterColumnError : Related error for missing cluster columns
     """
 
     def __init__(self, file_path: str, missing_params: list[str]):
-        """Initialize the error with the path to the problematic file and missing parameters.
-
-        Args:
-            file_path: Path to the file with missing parameters
-            missing_params: List of parameter names that are missing
+        """
+        Initialize the error with the path to the problematic file and missing parameters.
+
+        Parameters
+        ----------
+        file_path : str
+            Path to the file with missing parameters
+        missing_params : list[str]
+            List of parameter names that are missing
         """  # noqa: E501
         self.file_path = file_path
         self.missing_params = missing_params

clusx/logging.py

@@ -55,18 +55,14 @@ def get_logger(name: str) -> logging.Logger:
     """
     Get a logger with the specified name.
 
-    This function returns a logger instance configured with the specified name,
-    which is typically the module name (__name__). Using named loggers allows for
-    hierarchical logging configuration and makes it easier to identify the source
-    of log messages.
-
-    The returned logger inherits settings from the root logger configured by
-    setup_logging(), but can be further customized if needed.
-
-    Args:
-        name: The name for the logger (typically __name__)
-
-    Returns:
-        logging.Logger: A configured logger instance ready for use
+    Parameters
+    ----------
+    name : str
+        The name for the logger (typically ``__name__``).
+
+    Returns
+    -------
+    logging.Logger
+        A configured logger instance ready for use.
     """
     return logging.getLogger(name)

clusx/utils.py

@@ -19,15 +19,21 @@
 
 def to_numpy(embedding: EmbeddingTensor) -> NDArray[np.float32]:
     """
-    A helper function to convert a tensor to a numpy array.
+    Convert a tensor to a numpy array.
 
-    If embedding is already a numpy array (or compatible), it is returned as is.
-    Otherwise, it is converted to a numpy array.
+    This function uses duck typing to detect PyTorch tensors by checking for
+    the presence of the `detach()` method.
 
-    Args:
-        embedding: The tensor to convert.
+    Parameters
+    ----------
+    embedding : EmbeddingTensor
+        The tensor to convert. Can be a PyTorch tensor or a numpy array.
 
-    Returns: The numpy array.
+    Returns
+    -------
+    numpy.ndarray
+        The input converted to a numpy array. If the input is already a numpy array
+        (or compatible), it is returned as is.
     """
     # Use duck typing to check if this is a PyTorch tensor
     # PyTorch tensors have detach() method, numpy arrays don't

clusx/version.py

@@ -1,9 +1,10 @@
 """Version information.
 
-Provides package metadata through a cascading resolution strategy:
+This module provides package metadata through a cascading resolution strategy.
 
-1. Installed package metadata (via :mod:`importlib.metadata`)
-2. :file:`pyproject.toml` (for development environments)
+The metadata is resolved in the following order:
+1. Installed package metadata (via importlib.metadata)
+2. pyproject.toml (for development environments)
 3. Fallback defaults
 
 """