Documentation & overall project review

.github/workflows/ci.yaml

@@ -19,17 +19,14 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          submodules: recursive
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          submodules: recursive
-
       - name: Install system dependencies
         run: |
             sudo apt-get update
@@ -45,7 +42,7 @@ jobs:
         run: poetry run ruff check pysatl_experiment tests --output-format=github
 
       - name: Check formatting with Ruff
-        run: poetry run ruff format pysatl_experiment tests --check
+        run: poetry run ruff format --check pysatl_experiment tests
 
       - name: Run tests
         run: poetry run pytest --random-order tests

.pre-commit-config.yaml

@@ -25,10 +25,15 @@ repos:
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
     # Ruff version.
-    rev: 'v0.7.4'
+    rev: 'v0.11.12'
     hooks:
       - id: ruff
       - id: ruff-format
+      # Documentation
+      - id: ruff
+        name: ruff-docstrings
+        args: [ --select, D, --fix ]
+        log_file: ruff-docstrings.log
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0

mkdocs.yml

@@ -70,4 +70,9 @@ plugins:
       enabled: true
   - mike:
       deploy_prefix: 'en'
-      canonical_version: 'stable'
+      canonical_version: 'stable'
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: numpy

pyproject.toml

@@ -51,6 +51,7 @@ ruff = "0.11.12"
 pytest-mock = "3.14.1"
 pre-commit = "4.2.0"
 mypy = "^1.15.0"
+mkdocstrings-python = "^2.0.3"
 
 [tool.poetry.scripts]
 experiment = "pysatl_experiment.cli.cli.cli:cli"
@@ -70,17 +71,22 @@ line-length = 120
 extend-exclude = [".env", ".venv"]
 
 [tool.ruff.lint]
-extend-select = [
-  "C90", "B", "F", "E", "W", "UP", "I", "A", "TID", "YTT", "S", "PTH", "ASYNC", "NPY"
+select = [
+  "C90", "B", "F", "E", "W", "UP", "I", "A", "TID", "YTT", "S", "PTH", "ASYNC", "NPY", "D",
 ]
-extend-ignore = [
-  "E241", "E272", "E221", "B007", "B904", "S603", "S607", "S608", "NPY002"
+ignore = [
+  "E241", "E272", "E221", "B007", "B904", "S603", "S607", "S608", "NPY002",
+  "D107", "D203", "D212", "D213", "D401", "D404",
 ]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = [
-  "S101", "S104", "S311", "S105", "S106", "S110"
+  "S101", "S104", "S311", "S105", "S106", "S110", "D101", "D102", "D103",
 ]
+"**/__init__.py" = ["D104"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
 
 [tool.ruff.lint.mccabe]
 max-complexity = 12

pysatl_experiment/__main__.py

@@ -1,3 +1,9 @@
+"""
+CLI entrypoint module.
+
+Runs the command-line interface for the pysatl_experiment application.
+"""
+
 from pysatl_experiment.cli.cli.cli import cli
 
 

pysatl_experiment/cli/cli/cli.py

@@ -1,3 +1,5 @@
+"""Registration of CLI commands."""
+
 from pysatl_experiment.cli.commands.build_and_run.build_and_run import build_and_run
 from pysatl_experiment.cli.commands.configure.configure import configure
 from pysatl_experiment.cli.commands.create.create import create

pysatl_experiment/cli/commands/build_and_run/build_and_run.py

@@ -1,3 +1,7 @@
+"""CLI command for building and executing experiments."""
+
+from typing import Any, cast
+
 from click import BadParameter, argument, command
 
 from pysatl_experiment.cli.commands.common.common import normalize_experiment_name, read_experiment_data
@@ -12,17 +16,28 @@
 from pysatl_experiment.validation.cli.commands.common.common import if_experiment_exists
 
 
+# TODO: refactor names!
+
+
 @command()
 @argument("name")
 def build_and_run(name: str) -> None:
     """
-    Build and run an experiment with the given name.
+    Build and execute an experiment.
 
-    :param name: name of the experiment.
+    Parameters
+    ----------
+    name : str
+        Experiment name. The ``.json`` extension is optional.
+
+    Raises
+    ------
+    click.BadParameter
+        If the experiment does not exist.
     """
     name = normalize_experiment_name(name)
-    experiment_exists = if_experiment_exists(name)
-    if not experiment_exists:
+
+    if not if_experiment_exists(name):
         raise BadParameter(f"Experiment with name {name} does not exist.")
 
     experiment_data_dict = read_experiment_data(name)
@@ -35,21 +50,35 @@ def build_and_run(name: str) -> None:
 
 def _build_experiment(experiment_data: ExperimentData) -> ExperimentSteps:
     """
-    Build experiment from validated ExperimentData object.
+    Create experiment steps from validated configuration.
+
+    Parameters
+    ----------
+    experiment_data : ExperimentData
+        Validated experiment configuration.
 
-    :param experiment_data: validated experiment data.
-    :return: experiment steps.
+    Returns
+    -------
+    ExperimentSteps
+        Experiment steps ready for execution.
     """
     experiment_type_to_factory = {
         ExperimentType.POWER: PowerExperimentFactory,
         ExperimentType.CRITICAL_VALUE: CriticalValueExperimentFactory,
         ExperimentType.TIME_COMPLEXITY: TimeComplexityExperimentFactory,
     }
 
-    experiment_type_str = experiment_data.config.experiment_type.value
+    experiment_type = experiment_data.config.experiment_type
 
-    experiment_factory = experiment_type_to_factory[experiment_type_str]
+    experiment_factory = experiment_type_to_factory.get(experiment_type)
 
-    experiment_steps = experiment_factory(experiment_data).create_experiment_steps()
+    if experiment_factory is None:
+        raise BadParameter(f"Unsupported experiment type: {experiment_type}.")
 
-    return experiment_steps
+    validated_experiment_data = cast(
+        Any,
+        experiment_data,
+    )
+    return experiment_factory(
+        validated_experiment_data,
+    ).create_experiment_steps()