ci: Add numpydoc pre-commit hook

.github/workflows/backend.yml

@@ -38,7 +38,9 @@ jobs:
 
       - name: Lint
         working-directory: skore/
-        run: pre-commit run --all-files ruff
+        run: |
+          pre-commit run --all-files ruff
+          pre-commit run --all-files numpydoc-validation
 
   backend-lockfiles:
     runs-on: "ubuntu-latest"

.pre-commit-config.yaml

@@ -36,6 +36,12 @@ repos:
       - id: ruff-format
         files: ^(skore/(src|tests))|(examples)/
 
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
+    hooks:
+      - id: numpydoc-validation
+        files: ^(skore/src)/
+
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.15.0
     hooks:

examples/skore_project/plot_working_with_projects.py

@@ -120,7 +120,8 @@
 my_project.put(
     "my_string_2",
     (
-        """Hello world!, **bold**, *italic*, `code`
+        """
+        Hello world!, **bold**, *italic*, `code`
 
 ```python
 def my_func(x):

skore/pyproject.toml

@@ -117,6 +117,14 @@ convention = "numpy"
 "src/*" = ["UP007"]
 "tests/*" = ["D"]
 
+[tool.numpydoc_validation]
+checks = [
+  "all",  # Report on all checks, except the below
+  "ES01",  # No "extended summary" section
+  "EX01",  # No "Examples" section
+  "SA01",  # No "See also" section
+]
+
 [tool.typos.default]
 extend-ignore-re = [
   # Line ignore with trailing `# spellchecker:disable-line`

skore/src/skore/_config.py

@@ -13,7 +13,8 @@
 
 
 def _get_threadlocal_config() -> dict[str, Any]:
-    """Get a threadlocal **mutable** configuration.
+    """
+    Get a threadlocal **mutable** configuration.
 
     If the configuration does not exist, copy the default global configuration.
     """
@@ -23,7 +24,8 @@ def _get_threadlocal_config() -> dict[str, Any]:
 
 
 def get_config() -> dict[str, Any]:
-    """Retrieve current values for configuration set by :func:`set_config`.
+    """
+    Retrieve current values for configuration set by :func:`set_config`.
 
     Returns
     -------
@@ -50,7 +52,8 @@ def get_config() -> dict[str, Any]:
 def set_config(
     show_progress: Union[bool, None] = None,
 ) -> None:
-    """Set skore configuration.
+    """
+    Set skore configuration.
 
     Setting the configuration affects global settings meaning that it will be used
     by all skore functions and classes, even in the processes and threads spawned by
@@ -82,7 +85,8 @@ def config_context(
     *,
     show_progress: Union[bool, None] = None,
 ) -> Generator[None, None, None]:
-    """Context manager for skore configuration.
+    """
+    Context manager for skore configuration.
 
     Setting the configuration affects global settings meaning that it will be used
     by all skore functions and classes, even in the processes and threads spawned by
@@ -131,7 +135,8 @@ def config_context(
 
 
 def _set_show_progress_for_testing(show_progress: bool, sleep_duration: float) -> bool:
-    """Set the value of show_progress for testing purposes after some waiting.
+    """
+    Set the value of show_progress for testing purposes after some waiting.
 
     This function should exist in a Python module rather than in tests, otherwise
     joblib will not be able to pickle it.

skore/src/skore/exceptions.py

@@ -2,7 +2,8 @@
 
 
 class InvalidProjectNameError(Exception):
-    """The project name does not fit with one or more of the project name rules.
+    """
+    The project name does not fit with one or more of the project name rules.
 
     - The project name must start with an alphanumeric character, and must not contain
     special characters other than '_' (underscore) and '-' (hyphen).

skore/src/skore/externals/_pandas_accessors.py

@@ -1,4 +1,5 @@
-"""Pandas-like accessors.
+"""
+Pandas-like accessors.
 
 This code is copied from:
 https://github.com/pandas-dev/pandas/blob/main/pandas/core/accessor.py

skore/src/skore/externals/_sklearn_compat.py

@@ -1,6 +1,7 @@
 # ruff: noqa
 # mypy: ignore-errors
-"""Ease developer experience to support multiple versions of scikit-learn.
+"""
+Ease developer experience to support multiple versions of scikit-learn.
 
 This file is intended to be vendored in your project if you do not want to depend on
 `sklearn-compat` as a package. Then, you can import directly from this file.
@@ -40,7 +41,8 @@ def _dataclass_args():
 
 
 def get_tags(estimator):
-    """Get estimator tags in a consistent format across different sklearn versions.
+    """
+    Get estimator tags in a consistent format across different sklearn versions.
 
     This function provides compatibility between sklearn versions before and after 1.6.
     It returns either a Tags object (sklearn >= 1.6) or a converted Tags object from
@@ -172,7 +174,8 @@ def validate_params(parameter_constraints, *, prefer_skip_nested_validation):
 if sklearn_version < parse_version("1.4"):
 
     def _is_fitted(estimator, attributes=None, all_or_any=all):
-        """Determine if an estimator is fitted
+        """
+        Determine if an estimator is fitted
 
         Parameters
         ----------
@@ -384,7 +387,8 @@ def type_of_target(y, input_name="", *, raise_unknown=False):
         from sklearn.utils.multiclass import type_of_target
 
         def _raise_or_return(target_type):
-            """Depending on the value of raise_unknown, either raise an error or
+            """
+            Depending on the value of raise_unknown, either raise an error or
             return 'unknown'.
             """
             if raise_unknown and target_type == "unknown":
@@ -410,7 +414,8 @@ def validate_data(
         skip_check_array=False,
         **kwargs,
     ):
-        """Validate input data and set or check feature names and counts of the input.
+        """
+        Validate input data and set or check feature names and counts of the input.
 
         See the original scikit-learn documentation:
         https://scikit-learn.org/stable/modules/generated/sklearn.utils.validation.validate_data.html#sklearn.utils.validation.validate_data
@@ -468,7 +473,8 @@ def check_array(
         estimator=None,
         input_name="",
     ):
-        """Input validation on an array, list, sparse matrix or similar.
+        """
+        Input validation on an array, list, sparse matrix or similar.
 
         Check the original documentation for more details:
         https://scikit-learn.org/stable/modules/generated/sklearn.utils.check_array.html
@@ -523,7 +529,8 @@ def check_X_y(
         y_numeric=False,
         estimator=None,
     ):
-        """Input validation for standard estimators.
+        """
+        Input validation for standard estimators.
 
         Check the original documentation for more details:
         https://scikit-learn.org/stable/modules/generated/sklearn.utils.check_X_y.html
@@ -562,7 +569,8 @@ def check_X_y(
     # tags infrastructure
     @dataclass(**_dataclass_args())
     class InputTags:
-        """Tags for the input data.
+        """
+        Tags for the input data.
 
         Parameters
         ----------
@@ -622,7 +630,8 @@ class InputTags:
 
     @dataclass(**_dataclass_args())
     class TargetTags:
-        """Tags for the target data.
+        """
+        Tags for the target data.
 
         Parameters
         ----------
@@ -660,7 +669,8 @@ class TargetTags:
 
     @dataclass(**_dataclass_args())
     class TransformerTags:
-        """Tags for the transformer.
+        """
+        Tags for the transformer.
 
         Parameters
         ----------
@@ -679,7 +689,8 @@ class TransformerTags:
 
     @dataclass(**_dataclass_args())
     class ClassifierTags:
-        """Tags for the classifier.
+        """
+        Tags for the classifier.
 
         Parameters
         ----------
@@ -706,7 +717,8 @@ class ClassifierTags:
 
     @dataclass(**_dataclass_args())
     class RegressorTags:
-        """Tags for the regressor.
+        """
+        Tags for the regressor.
 
         Parameters
         ----------
@@ -727,7 +739,8 @@ class RegressorTags:
 
     @dataclass(**_dataclass_args())
     class Tags:
-        """Tags for the estimator.
+        """
+        Tags for the estimator.
 
         See :ref:`estimator_tags` for more information.
 

skore/src/skore/persistence/item/altair_chart_item.py

@@ -1,4 +1,5 @@
-"""AltairChartItem.
+"""
+AltairChartItem.
 
 This module defines the AltairChartItem class, used to persist Altair Charts.
 """

skore/src/skore/persistence/item/item.py

@@ -9,7 +9,8 @@
 
 
 class ItemTypeError(Exception):
-    """Item type exception.
+    """
+    Item type exception.
 
     Exception raised when an attempt is made to convert an object to an Item, but the
     object's type is not supported.

skore/src/skore/persistence/item/matplotlib_figure_item.py

@@ -1,4 +1,5 @@
-"""MatplotlibFigureItem.
+"""
+MatplotlibFigureItem.
 
 This module defines the MatplotlibFigureItem class, used to persist Matplotlib figures.
 """

skore/src/skore/persistence/item/media_item.py

@@ -1,4 +1,5 @@
-"""MediaItem.
+"""
+MediaItem.
 
 This module defines the MediaItem class, used to persist media.
 """

skore/src/skore/persistence/item/numpy_array_item.py

@@ -1,4 +1,5 @@
-"""NumpyArrayItem.
+"""
+NumpyArrayItem.
 
 This module defines the NumpyArrayItem class, which represents a NumPy array item.
 """

skore/src/skore/persistence/item/pandas_dataframe_item.py

@@ -1,4 +1,5 @@
-"""PandasDataFrameItem.
+"""
+PandasDataFrameItem.
 
 This module defines the PandasDataFrameItem class,
 which represents a pandas DataFrame item.

skore/src/skore/persistence/item/pandas_series_item.py

@@ -1,4 +1,5 @@
-"""PandasSeriesItem.
+"""
+PandasSeriesItem.
 
 This module defines the PandasSeriesItem class,
 which represents a pandas Series item.

skore/src/skore/persistence/item/pickle_item.py

@@ -1,4 +1,5 @@
-"""PickleItem.
+"""
+PickleItem.
 
 This module defines the PickleItem class, which is used to persist objects that cannot
 be otherwise.

skore/src/skore/persistence/item/pillow_image_item.py

@@ -1,4 +1,5 @@
-"""PillowImageItem.
+"""
+PillowImageItem.
 
 This module defines the PillowImageItem class, used to persist Pillow images.
 """

skore/src/skore/persistence/item/plotly_figure_item.py

@@ -1,4 +1,5 @@
-"""PlotlyFigureItem.
+"""
+PlotlyFigureItem.
 
 This module defines the PlotlyFigureItem class, used to persist Plotly figures.
 """

skore/src/skore/persistence/item/polars_dataframe_item.py

@@ -1,4 +1,5 @@
-"""PolarsDataFrameItem.
+"""
+PolarsDataFrameItem.
 
 This module defines the PolarsDataFrameItem class,
 which represents a polars DataFrame item.

skore/src/skore/persistence/item/polars_series_item.py

@@ -1,4 +1,5 @@
-"""PolarsSeriesItem.
+"""
+PolarsSeriesItem.
 
 This module defines the PolarsSeriesItem class,
 which represents a polars Series item.

skore/src/skore/persistence/item/primitive_item.py

@@ -1,4 +1,5 @@
-"""Define PrimitiveItem.
+"""
+Define PrimitiveItem.
 
 PrimitiveItems represents a primitive item with creation and update timestamps.
 """

skore/src/skore/persistence/item/sklearn_base_estimator_item.py

@@ -1,4 +1,5 @@
-"""SklearnBaseEstimatorItem.
+"""
+SklearnBaseEstimatorItem.
 
 This module defines the SklearnBaseEstimatorItem class,
 which represents a scikit-learn BaseEstimator item.

skore/src/skore/persistence/repository/item_repository.py

@@ -1,4 +1,5 @@
-"""ItemRepository for managing storage and retrieval of items.
+"""
+ItemRepository for managing storage and retrieval of items.
 
 This module provides the ItemRepository class, which is responsible for
 storing, retrieving, and deleting items in a storage system.
@@ -146,7 +147,8 @@ def __iter__(self) -> Iterator[str]:
         yield from self.storage
 
     def set_item_note(self, key: str, note: str, *, version=-1):
-        """Attach a note to key ``key``.
+        """
+        Attach a note to key ``key``.
 
         Parameters
         ----------
@@ -178,7 +180,8 @@ def set_item_note(self, key: str, note: str, *, version=-1):
             raise KeyError((key, version)) from e
 
     def get_item_note(self, key: str, *, version=-1) -> Union[str, None]:
-        """Retrieve a note previously attached to key ``key``.
+        """
+        Retrieve a note previously attached to key ``key``.
 
         Parameters
         ----------
@@ -203,7 +206,8 @@ def get_item_note(self, key: str, *, version=-1) -> Union[str, None]:
             raise KeyError((key, version)) from e
 
     def delete_item_note(self, key: str, *, version=-1):
-        """Delete a note previously attached to key ``key``.
+        """
+        Delete a note previously attached to key ``key``.
 
         Parameters
         ----------

skore/src/skore/persistence/view/view.py

@@ -8,7 +8,8 @@
 
 @dataclass
 class View:
-    """A view of a Project.
+    """
+    A view of a Project.
 
     Examples
     --------