chore: add type hints and doctrings

.pre-commit-config.yaml

@@ -5,32 +5,32 @@ repos:
   - id: clear-notebooks-output
     name: clear-notebooks-output
     files: tools/.*\.ipynb$
-    stages: [pre-commit]
+    stages: [ pre-commit ]
     language: python
     entry: jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace
-    additional_dependencies: [jupyter]
+    additional_dependencies: [ jupyter ]
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v5.0.0
   hooks:
   - id: check-yaml # Check YAML files for syntax errors only
-    args: [--unsafe, --allow-multiple-documents]
+    args: [ --unsafe, --allow-multiple-documents ]
   - id: debug-statements # Check for debugger imports and py37+ breakpoint()
   - id: end-of-file-fixer # Ensure files end in a newline
   - id: trailing-whitespace # Trailing whitespace checker
   - id: no-commit-to-branch # Prevent committing to main / master
   - id: check-added-large-files # Check for large files added to git
   - id: check-merge-conflict # Check for files that contain merge conflict
--   repo: https://github.com/pre-commit/pygrep-hooks
-    rev: v1.10.0  # Use the ref you want to point at
-    hooks:
-    -   id: python-use-type-annotations # Check for missing type annotations
-    -   id: python-check-blanket-noqa # Check for # noqa: all
-    -   id: python-no-log-warn # Check for log.warn
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: v1.10.0 # Use the ref you want to point at
+  hooks:
+  - id: python-use-type-annotations # Check for missing type annotations
+  - id: python-check-blanket-noqa # Check for # noqa: all
+  - id: python-no-log-warn # Check for log.warn
 - repo: https://github.com/psf/black-pre-commit-mirror
   rev: 24.10.0
   hooks:
   - id: black
-    args: [--line-length=120]
+    args: [ --line-length=120 ]
 - repo: https://github.com/pycqa/isort
   rev: 5.13.2
   hooks:
@@ -63,21 +63,27 @@ repos:
   rev: "0.1.4"
   hooks:
   - id: docconvert
-    args: ["numpy"]
+    args: [ "numpy" ]
 - repo: https://github.com/tox-dev/pyproject-fmt
   rev: "v2.5.0"
   hooks:
   - id: pyproject-fmt
--   repo: https://github.com/jshwi/docsig # Check docstrings against function sig
-    rev: v0.66.1
-    hooks:
-    -   id: docsig
-        args:
-        - --ignore-no-params # Allow docstrings without parameters
-        - --check-dunders    # Check dunder methods
-        - --check-overridden # Check overridden methods
-        - --check-protected  # Check protected methods
-        - --check-class      # Check class docstrings
-        - --disable=SIG101,SIG102     # Disable empty docstrings
+- repo: https://github.com/jshwi/docsig # Check docstrings against function sig
+  rev: v0.66.1
+  hooks:
+  - id: docsig
+    args:
+    - --ignore-no-params # Allow docstrings without parameters
+    - --check-dunders # Check dunder methods
+    - --check-overridden # Check overridden methods
+    - --check-protected # Check protected methods
+    - --check-class # Check class docstrings
+    # - --disable=SIG503    # Disable empty docstrings
+
+- repo: https://github.com/DanielNoord/pydocstringformatter
+  rev: "v0.7.3"
+  hooks:
+  - id: pydocstringformatter
+
 ci:
   autoupdate_schedule: monthly

pyproject.toml

@@ -54,7 +54,7 @@ optional-dependencies.docs = [
   "nbsphinx",
   "pandoc",
   "requests",
-  "sphinx",
+  "sphinx<8.2",
   "sphinx-argparse<0.5",
   "sphinx-rtd-theme",
   "termcolor",
@@ -71,3 +71,14 @@ scripts.anemoi-transform = "anemoi.transform.__main__:main"
 
 [tool.setuptools_scm]
 version_file = "src/anemoi/transform/_version.py"
+
+[tool.mypy]
+strict = false
+exclude = [
+  "docs/**",
+]
+
+[tool.pydocstringformatter]
+write = true
+exclude = "docs/**"
+style = "numpydoc"

src/anemoi/transform/__init__.py

@@ -10,7 +10,7 @@
 try:
     # NOTE: the `_version.py` file must not be present in the git repository
     #   as it is generated by setuptools at install time
-    from ._version import __version__  # type: ignore
+    from ._version import __version__
 except ImportError:  # pragma: no cover
     # Local copy or not installed with setuptools
     __version__ = "999"

src/anemoi/transform/__main__.py

@@ -7,6 +7,8 @@
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
 
+from argparse import ArgumentParser
+
 from anemoi.utils.cli import cli_main
 from anemoi.utils.cli import make_parser
 
@@ -15,11 +17,19 @@
 
 
 # For read-the-docs
-def create_parser():
+def create_parser() -> ArgumentParser:
+    """Creates the argument parser for the CLI.
+
+    Returns
+    -------
+    ArgumentParser
+        The argument parser.
+    """
     return make_parser(__doc__, COMMANDS)
 
 
-def main():
+def main() -> None:
+    """The main entry point for the CLI."""
     cli_main(__version__, __doc__, COMMANDS)
 
 

src/anemoi/transform/commands/__init__.py

@@ -7,6 +7,18 @@
 # granted to it by virtue of its status as an intergovernmental organisation
 # nor does it submit to any jurisdiction.
 
+"""This module provides the command line interface for the Anemoi transform commands.
+
+Commands
+--------
+Command : class
+    Base class for all commands.
+Failed : class
+    Class representing a failed command.
+register_commands : function
+    Function to register commands.
+"""
+
 import os
 
 from anemoi.utils.cli import Command

src/anemoi/transform/commands/get-grid.py

@@ -8,18 +8,34 @@
 # nor does it submit to any jurisdiction.
 
 
+import argparse
+
 from . import Command
 
 
 class GetGrid(Command):
     """Extract the grid from a GRIB or NetCDF file and save it as a NPZ file."""
 
-    def add_arguments(self, command_parser):
+    def add_arguments(self, command_parser: argparse.ArgumentParser) -> None:
+        """Add arguments to the command parser.
+
+        Parameters
+        ----------
+        command_parser : argparse.ArgumentParser
+            The argument parser to add arguments to.
+        """
         command_parser.add_argument("--source", default="file", help="EKD Source type (default: file).")
         command_parser.add_argument("input", help="Input file (GRIB or NetCDF).")
         command_parser.add_argument("output", help="Output NPZ file.")
 
-    def run(self, args):
+    def run(self, args: argparse.Namespace) -> None:
+        """Run the command with the provided arguments.
+
+        Parameters
+        ----------
+        args : argparse.Namespace
+            The arguments to run the command with.
+        """
         import numpy as np
         from earthkit.data import from_source
 

src/anemoi/transform/commands/make-regrid-matrix.py

@@ -8,6 +8,7 @@
 # nor does it submit to any jurisdiction.
 
 
+import argparse
 import os
 
 from . import Command
@@ -18,7 +19,14 @@ class MakeRegridMatrix(Command):
     by earthkit-regrid.
     """
 
-    def add_arguments(self, command_parser):
+    def add_arguments(self, command_parser: argparse.ArgumentParser) -> None:
+        """Add arguments to the command parser.
+
+        Parameters
+        ----------
+        command_parser : argparse.ArgumentParser
+            The argument parser to add arguments to.
+        """
         command_parser.add_argument("--source1", default="file", help="EKD Source type (default: file).")
         command_parser.add_argument("--source2", default="file", help="EKD Source type (default: file).")
 
@@ -31,7 +39,14 @@ def add_arguments(self, command_parser):
 
         command_parser.add_argument("kwargs", nargs="*", help="MIR arguments.")
 
-    def run(self, args):
+    def run(self, args: argparse.Namespace) -> None:
+        """Run the command with the provided arguments.
+
+        Parameters
+        ----------
+        args : argparse.Namespace
+            The arguments to run the command with.
+        """
         import numpy as np
         from earthkit.data import from_source
         from earthkit.regrid.utils.mir import mir_make_matrix