🔧 Improve linting, docstring formatting, and type hints

.dprint.jsonc

@@ -12,7 +12,7 @@
     "formatComments": true,
     "braceSpacing": false,
   },
-  "excludes": ["**/*.lock", "dist/"],
+  "excludes": ["**/*-lock.json", "**/*.lock", "**/node_modules/", "dist/"],
   "plugins": [
     "https://plugins.dprint.dev/json-0.20.0.wasm",
     "https://plugins.dprint.dev/markdown-0.19.0.wasm",

.gitignore

@@ -220,5 +220,8 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 
+# Type Stubs
+typings/
+
 # Plots
 demos/ITER/plots/

.lefthook.yaml

@@ -1,7 +1,7 @@
-lefthook: pixi run --environment=lint lefthook
+lefthook: pixi run --no-progress --environment=lint --frozen lefthook
 
 templates:
-  run: run --environment=lint
+  run: run --quiet --no-progress --environment=lint --frozen
 
 colors: true
 
@@ -65,18 +65,6 @@ pre-commit:
       glob: "pyproject.toml"
       run: pixi {run} validate-pyproject {staged_files}
 
-    - name: docstring-lint
-      stage_fixed: true
-      group:
-        piped: true
-        jobs:
-          - name: docformatter
-            glob: "*.{py,pyx,pyi}"
-            run: pixi {run} docformatter --in-place {staged_files}
-          - name: numpydoc
-            glob: "*.{py,pyi}"
-            run: pixi {run} numpydoc {staged_files}
-
     - name: cython-lint
       glob: "*.{pyx,pxd}"
       run: pixi {run} cython-lint {staged_files}

CHANGELOG.md

@@ -2,8 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https//keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https//semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] - 2025-11-18
+
+### Added
+
+- Add some missing type hints.
+
+### Changed
+
+- Migrate docstring linting/formatting from `numpydoc` and `docformatter` to `ruff`
+- Migrate `numpydoc` Python API reference to `napoleon` extension for Sphinx (to enjoy type hinting support)
+- Update docstrings to be compatible with the `napoleon` style
+
+### Fixed
+
+- Fix values assignment in `load_equilibrium_data` function (convert to python types)
+- Bug fix in `load_unstruct_grid_2d` function (incorrect `cells.append(cell)` line)
+
+### Removed
+
+- Remove `numpydoc` dependency (migrated to `ruff` for docstring linting as well)
+- Remove `docformatter` dependency (migrated to `ruff` for docstring formatting as well)
 
 ## [0.2.0] - 2025-11-04
 

demos/ITER/camera_geometry_matrix_gif.py

@@ -62,7 +62,7 @@
 unsaturated_fraction = 0.95
 
 
-def read_geometry_matrix_without_reflections(
+def read_geometry_matrix_without_reflections(  # noqa: D103
     shot, run, user, database="ITER_MD", backend=HDF5_BACKEND
 ):
     geometry_matrix = {}
@@ -96,7 +96,7 @@ def read_geometry_matrix_without_reflections(
     return geometry_matrix
 
 
-def read_geometry_matrix_interpolated(shot, run, user, database="ITER_MD", backend=HDF5_BACKEND):
+def read_geometry_matrix_interpolated(shot, run, user, database="ITER_MD", backend=HDF5_BACKEND):  # noqa: D103
     geometry_matrix = {}
 
     with DBEntry(backend, database, shot, run, user) as entry:
@@ -235,7 +235,7 @@ def read_geometry_matrix_interpolated(shot, run, user, database="ITER_MD", backe
         power = volume[index] * line_emission[il, it][index]
         points = np.array([r2d[index], z2d[index]]).T
 
-        def f(task, node_points, interp_data, points, power):
+        def _f(task, node_points, interp_data, points, power):
             ibegin = task[0]
             iend = task[1]
             interp_matrix = griddata(
@@ -252,7 +252,7 @@ def f(task, node_points, interp_data, points, power):
 
         with ctx.Pool(processes=NPROC) as pool:
             results = pool.map(
-                f,
+                _f,
                 tasks,
                 node_points=node_points,
                 interp_data=interp_data,

demos/ITER/core_plasma_plot_profiles.py

@@ -10,6 +10,7 @@
 import numpy as np
 from matplotlib import pyplot as plt
 from matplotlib.colors import SymLogNorm
+from matplotlib.figure import Figure
 
 from cherab.core.math import sample3d_grid, samplevector2d
 from cherab.imas.datasets import iter_jintrac
@@ -19,9 +20,26 @@
 plt.ion()
 
 
-def plot_quantity(quantity, extent, title="", logscale=False, symmetric=False):
-    """Make a 2D plot of quantity, with a title, optionally on a log scale."""
-
+def plot_quantity(quantity, extent, title="", logscale=False, symmetric=False) -> Figure:
+    """Make a 2D plot of quantity, with a title, optionally on a log scale.
+
+    Parameters
+    ----------
+    quantity
+        2D array of the quantity to plot.
+    extent
+        The extent of the plot in the form [xmin, xmax, ymin, ymax].
+    title
+        The title of the plot.
+    logscale
+        Whether to use a logarithmic scale for the color map.
+    symmetric
+        Whether to use a symmetric color map around zero.
+
+    Returns
+    -------
+    The matplotlib Figure object containing the plot.
+    """
     fig = plt.figure(figsize=(4.0, 6.0), layout="constrained")
     ax = fig.add_subplot(111)
     if logscale:

demos/ITER/edge_plasma_mesh_and_values.py

@@ -10,6 +10,7 @@
 import numpy as np
 from matplotlib import pyplot as plt
 from matplotlib.colors import SymLogNorm
+from matplotlib.figure import Figure
 
 from cherab.imas.datasets import iter_jintrac
 from cherab.imas.ids.common import get_ids_time_slice
@@ -21,7 +22,26 @@
 grid_subset_name = "Cells"
 
 
-def plot_grid_quantity(grid, quantity, title="", logscale=False, symmetric=False):
+def plot_grid_quantity(grid, quantity, title="", logscale=False, symmetric=False) -> Figure:
+    """Make a 2D plot of a grid quantity, with a title, optionally on a log scale.
+
+    Parameters
+    ----------
+    grid
+        The grid object.
+    quantity
+        1D array of the quantity to plot on the grid.
+    title
+        The title of the plot.
+    logscale
+        Whether to use a logarithmic scale for the color map.
+    symmetric
+        Whether to use a symmetric color map around zero.
+
+    Returns
+    -------
+    The matplotlib Figure object containing the plot.
+    """
     ax = grid.plot_mesh(data=quantity)
 
     if logscale:

demos/ITER/edge_plasma_plot_profiles.py

@@ -9,6 +9,7 @@
 import numpy as np
 from matplotlib import pyplot as plt
 from matplotlib.colors import SymLogNorm
+from matplotlib.figure import Figure
 
 from cherab.core.math import sample3d, sample3d_grid, samplevector2d, samplevector3d_grid
 from cherab.imas.datasets import iter_jintrac
@@ -18,9 +19,26 @@
 plt.ion()
 
 
-def plot_quantity(quantity, extent, title="", logscale=False, symmetric=False):
-    """Make a 2D plot of quantity, with a title, optionally on a log scale."""
-
+def plot_quantity(quantity, extent, title="", logscale=False, symmetric=False) -> Figure:
+    """Make a 2D plot of quantity, with a title, optionally on a log scale.
+
+    Parameters
+    ----------
+    quantity
+        2D array of the quantity to plot.
+    extent
+        The extent of the plot in the form [xmin, xmax, ymin, ymax].
+    title
+        The title of the plot.
+    logscale
+        Whether to use a logarithmic scale for the color map.
+    symmetric
+        Whether to use a symmetric color map around zero.
+
+    Returns
+    -------
+    The matplotlib Figure object containing the plot.
+    """
     fig = plt.figure(figsize=(4.0, 6.0), layout="constrained")
     ax = fig.add_subplot(111)
     if logscale:

demos/ITER/full_plasma_plot_profiles.py

@@ -10,6 +10,7 @@
 import numpy as np
 from matplotlib import pyplot as plt
 from matplotlib.colors import SymLogNorm
+from matplotlib.figure import Figure
 
 from cherab.core.math import sample3d, sample3d_grid, samplevector2d, samplevector3d_grid
 from cherab.imas.datasets import iter_jintrac
@@ -19,9 +20,26 @@
 plt.ion()
 
 
-def plot_quantity(quantity, extent, title="", logscale=False, symmetric=False):
-    """Make a 2D plot of quantity, with a title, optionally on a log scale."""
-
+def plot_quantity(quantity, extent, title="", logscale=False, symmetric=False) -> Figure:
+    """Make a 2D plot of quantity, with a title, optionally on a log scale.
+
+    Parameters
+    ----------
+    quantity
+        2D array of the quantity to plot.
+    extent
+        The extent of the plot in the form [xmin, xmax, ymin, ymax].
+    title
+        The title of the plot.
+    logscale
+        Whether to use a logarithmic scale for the color map.
+    symmetric
+        Whether to use a symmetric color map around zero.
+
+    Returns
+    -------
+    The matplotlib figure object.
+    """
     fig = plt.figure(figsize=(4.0, 6.0), layout="constrained")
     ax = fig.add_subplot(111)
     if logscale:

docs/notebooks/plasma/full_plasma.ipynb

@@ -393,7 +393,7 @@
     "            title=\"Density of \" + label,\n",
     "            clabel=\"[1/m³]\",\n",
     "            logscale=True,\n",
-    "        )\n"
+    "        )"
    ]
   }
  ],

docs/source/_templates/class.rst

@@ -5,31 +5,29 @@
 .. autoclass:: {{ objname }}
    :show-inheritance:
    :members:
+   :special-members: __call__, __getitem__
    :inherited-members:
-
-   {% block methods %}
-   {% if all_methods %}
+{% block methods %}
+{% if all_methods %}
    .. rubric:: {{ _('Methods') }}
 
    .. autosummary::
       :template: method.rst
-
-   {% for item in all_methods %}
-   {%- if not item.startswith('_') or item in ['__call__', '__getitem__'] %}
+{% for item in all_methods %}
+{%- if not item.startswith('_') or item in ['__call__', '__getitem__'] %}
       ~{{ name }}.{{ item }}
-   {% endif %}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block attributes %}
-   {% if attributes %}
+{%- endif -%}
+{%- endfor -%}
+{%- endif -%}
+{% endblock %}
+{% block attributes %}
+{% if attributes %}
    .. rubric:: {{ _('Attributes') }}
 
    .. autosummary::
       :template: attribute.rst
-   {% for item in attributes %}
+{% for item in attributes %}
       ~{{ name }}.{{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
+{%- endfor %}
+{%- endif %}
+{% endblock %}