MAINT: Modernize numpydoc validation

Author: larsoner

doc/conf.py

@@ -27,7 +27,6 @@
 
 import mne
 import mne.html_templates._templates
-from mne.tests.test_docstring_parameters import error_ignores
 from mne.utils import (
     linkcode_resolve,
     run_subprocess,
@@ -432,42 +431,6 @@
     "pooch.HTTPDownloader",
 }
 numpydoc_validate = True
-numpydoc_validation_checks = {"all"} | set(error_ignores)
-numpydoc_validation_exclude = {  # set of regex
-    # dict subclasses
-    r"\.clear",
-    r"\.get$",
-    r"\.copy$",
-    r"\.fromkeys",
-    r"\.items",
-    r"\.keys",
-    r"\.move_to_end",
-    r"\.pop",
-    r"\.popitem",
-    r"\.setdefault",
-    r"\.update",
-    r"\.values",
-    # list subclasses
-    r"\.append",
-    r"\.count",
-    r"\.extend",
-    r"\.index",
-    r"\.insert",
-    r"\.remove",
-    r"\.sort",
-    # we currently don't document these properly (probably okay)
-    r"\.__getitem__",
-    r"\.__contains__",
-    r"\.__hash__",
-    r"\.__mul__",
-    r"\.__sub__",
-    r"\.__add__",
-    r"\.__iter__",
-    r"\.__div__",
-    r"\.__neg__",
-    # copied from sklearn
-    r"mne\.utils\.deprecated",
-}
 
 
 # -- Sphinx-gallery configuration --------------------------------------------

mne/epochs.py

@@ -979,6 +979,11 @@ def iter_evoked(self, copy=False):
         copy : bool
             If False copies of data and measurement info will be omitted
             to save time.
+
+        Yields
+        ------
+        evoked : instance of Evoked
+            The epochs as a sequence of Evoked objects, one per epoch.
         """
         self.__iter__()
 

mne/forward/_make_forward.py

@@ -947,7 +947,7 @@ def _to_forward_dict(
 
 
 @contextmanager
-def use_coil_def(fname):
+def use_coil_def(fname):  # numpydoc ignore=YD01
     """Use a custom coil definition file.
 
     Parameters

mne/tests/test_docstring_parameters.py

@@ -48,6 +48,20 @@
     "mne.viz",
 ]
 
+pyproject_path = Path(__file__).parents[2] / "pyproject.toml"
+if not pyproject_path.is_file():
+    pytest.skip(f"pyproject.toml not found: {pyproject_path}", allow_module_level=True)
+try:
+    import tomllib
+except ModuleNotFoundError:
+    # TODO VERSION: Remove this when Python 3.11+ is required
+    pytest.skip("tomllib not available", allow_module_level=True)
+
+pyproject = tomllib.loads(pyproject_path.read_text("utf-8"))
+numpydoc_checks = pyproject["tool"]["numpydoc_validation"]["checks"]
+assert numpydoc_checks[0] == "all"
+error_ignores = set(numpydoc_checks[1:])
+
 
 def _func_name(func, cls=None):
     """Get the name."""
@@ -73,21 +87,6 @@ def _func_name(func, cls=None):
     "mne.channels.tests.test_montage",
     "mne.io.curry.tests.test_curry",
 ]
-error_ignores = {
-    # These we do not live by:
-    "GL01",  # Docstring should start in the line immediately after the quotes
-    "GL02",  # Closing quotes on own line (doesn't work on Python 3.13 anyway)
-    "EX01",
-    "EX02",  # examples failed (we test them separately)
-    "ES01",  # no extended summary
-    "SA01",  # no see also
-    "YD01",  # no yields section
-    "SA04",  # no description in See Also
-    "PR04",  # Parameter "shape (n_channels" has no type
-    "RT02",  # The first line of the Returns section should contain only the type, unless multiple values are being returned  # noqa
-    # XXX should also verify that | is used rather than , to separate params
-    # XXX should maybe also restore the parameter-desc-length < 800 char check
-}
 error_ignores_specific = {  # specific instances to skip
     ("regress_artifact", "SS05"),  # "Regress" is actually imperative
 }

mne/time_frequency/tfr.py

@@ -3387,6 +3387,11 @@ def iter_evoked(self, copy=False):
         ----------
         copy : bool
             Whether to yield copies of the data and measurement info, or views/pointers.
+
+        Yields
+        ------
+        epoch : instance of AverageTFR
+            The time-frequency data for a single epoch, wrapped in an AverageTFR object.
         """
         self.__iter__()
         state = self.__getstate__()

mne/utils/docs.py

@@ -5238,7 +5238,7 @@ def wrapper(func):
             raise ValueError("Cannot copy docstring: docstring was empty.")
         doc = source.__doc__
         if func.__doc__ is not None:
-            doc += f"\n{inspect.cleandoc(func.__doc__)}"
+            doc += f"\n{inspect.cleandoc(func.__doc__)}\n"
         func.__doc__ = doc
         return func
 
@@ -5388,6 +5388,8 @@ def wrapper(func):
             + "\n".join(doc[first_parameter_end:])
         )
         func.__doc__ = f"{doc}{func_doc}"
+        if not func.__doc__.endswith("\n\n"):
+            func.__doc__ = func.__doc__ + "\n"
         return func
 
     return wrapper

mne/viz/_figure.py

@@ -882,7 +882,7 @@ def get_browser_backend():
 
 
 @contextmanager
-def use_browser_backend(backend_name):
+def use_browser_backend(backend_name):  # numpydoc ignore=YD01
     """Create a 2D browser visualization context using the designated backend.
 
     See :func:`mne.viz.set_browser_backend` for more details on the available

mne/viz/backends/renderer.py

@@ -202,7 +202,7 @@ def _get_3d_backend():
 
 
 @contextmanager
-def use_3d_backend(backend_name):
+def use_3d_backend(backend_name):  # numpydoc ignore=YD01
     """Create a 3d visualization context using the designated backend.
 
     See :func:`mne.viz.set_3d_backend` for more details on the available

pyproject.toml

@@ -279,6 +279,54 @@ disable_error_code = [
 ignore_errors = false
 module = ['mne.annotations', 'mne.epochs', 'mne.evoked', 'mne.io']
 
+[tool.numpydoc_validation]
+checks = [
+  "all",  # report on all checks, except the below
+  "ES01",  # no extended summary
+  "EX01",  # no examples
+  "EX02",  # examples failed (we test them separately)
+  "GL01",  # Docstring should start in the line immediately after the quotes
+  "PR04",  # Parameter "shape (n_channels" has no type
+  "RT02",  # The first line of the Returns section should contain only the type, unless multiple values are being returned  # noqa
+  "SA01",  # no see also
+  "SA04",  # no description in See Also
+]
+exclude = [
+  # dict subclasses
+  '\.clear',
+  '\.get$',
+  '\.copy$',
+  '\.fromkeys',
+  '\.items',
+  '\.keys',
+  '\.move_to_end',
+  '\.pop',
+  '\.popitem',
+  '\.setdefault',
+  '\.update',
+  '\.values',
+  # list subclasses
+  '\.append',
+  '\.count',
+  '\.extend',
+  '\.index',
+  '\.insert',
+  '\.remove',
+  '\.sort',
+  # we currently don't document these properly (probably okay)
+  '\.__getitem__',
+  '\.__contains__',
+  '\.__hash__',
+  '\.__mul__',
+  '\.__sub__',
+  '\.__add__',
+  '\.__iter__',
+  '\.__div__',
+  '\.__neg__',
+  # copied from sklearn
+  'mne\.utils\.deprecated',
+]
+
 [tool.pytest.ini_options]
 # -r f (failed), E (error), s (skipped), x (xfail), X (xpassed), w (warnings)
 # don't put in xfail for pytest 8.0+ because then it prints the tracebacks,
@@ -408,6 +456,9 @@ ignore_case = true
 spaces_before_inline_comment = 2
 trailing_comma_inline_array = true
 
+[tool.tomlsort.overrides."tool.numpydoc_validation.exclude"]
+inline_arrays = false
+
 [tool.towncrier]
 directory = "doc/changes/dev/"
 filename = "doc/changes/dev.rst"