Add numpydoc_validation_overrides option to Sphinx extension side.

Author: stefmolin

numpydoc/numpydoc.py

@@ -207,7 +207,19 @@ def mangle_docstrings(app, what, name, obj, options, lines):
                 # TODO: Currently, all validation checks are run and only those
                 # selected via config are reported. It would be more efficient to
                 # only run the selected checks.
-                errors = validate(doc)["errors"]
+                report = validate(doc)
+                errors = [
+                    err
+                    for err in report["errors"]
+                    if not (
+                        (
+                            overrides := app.config.numpydoc_validation_overrides.get(
+                                err[0]
+                            )
+                        )
+                        and re.search(overrides, report["docstring"])
+                    )
+                ]
                 if {err[0] for err in errors} & app.config.numpydoc_validation_checks:
                     msg = (
                         f"[numpydoc] Validation warnings while processing "
@@ -285,6 +297,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value("numpydoc_xref_ignore", set(), True)
     app.add_config_value("numpydoc_validation_checks", set(), True)
     app.add_config_value("numpydoc_validation_exclude", set(), False)
+    app.add_config_value("numpydoc_validation_overrides", dict(), False)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)
@@ -327,6 +340,11 @@ def update_config(app, config=None):
         )
         config.numpydoc_validation_excluder = exclude_expr
 
+    for check, patterns in config.numpydoc_validation_overrides.items():
+        config.numpydoc_validation_overrides[check] = re.compile(
+            r"|".join(exp for exp in patterns)
+        )
+
 
 # ------------------------------------------------------------------------------
 # Docstring-mangling domains

numpydoc/tests/test_docscrape.py

@@ -1576,6 +1576,7 @@ def __init__(self, a, b):
             # numpydoc.update_config fails if this config option not present
             self.numpydoc_validation_checks = set()
             self.numpydoc_validation_exclude = set()
+            self.numpydoc_validation_overrides = dict()
 
     xref_aliases_complete = deepcopy(DEFAULT_LINKS)
     for key in xref_aliases:

numpydoc/tests/test_numpydoc.py

@@ -23,6 +23,7 @@ class MockConfig:
     numpydoc_attributes_as_param_list = True
     numpydoc_validation_checks = set()
     numpydoc_validation_exclude = set()
+    numpydoc_validation_overrides = dict()
 
 
 class MockBuilder:
@@ -212,6 +213,39 @@ def function_with_bad_docstring():
     assert warning.getvalue() == ""
 
 
+@pytest.mark.parametrize("overrides", [{}, {"SS02"}, {"SS02", "SS03"}])
+def test_mangle_docstrings_overrides(overrides):
+    def process_something_noop_function():
+        """Process something."""
+
+    app = MockApp()
+    app.config.numpydoc_validation_checks = {"all"}
+    app.config.numpydoc_validation_overrides = {
+        check: [r"^Process "]  # overrides are regex on docstring content
+        for check in overrides
+    }
+    update_config(app)
+
+    # Setup for catching warnings
+    status, warning = StringIO(), StringIO()
+    logging.setup(app, status, warning)
+
+    # Run mangle docstrings on process_something_noop_function
+    mangle_docstrings(
+        app,
+        "function",
+        process_something_noop_function.__name__,
+        process_something_noop_function,
+        None,
+        process_something_noop_function.__doc__.split("\n"),
+    )
+
+    findings = warning.getvalue()
+    assert " EX01: " in findings  # should always be there
+    for check in overrides:
+        assert f" {check}: " not in findings
+
+
 def test_update_config_invalid_validation_set():
     app = MockApp()
     # Results in {'a', 'l'} instead of {"all"}