Add feature to exclude patterns from docstring validation.

Modify updated config name to avoid sphinx warning.

Add documentation for exclusion config value.

Author: rossbar

doc/install.rst

@@ -121,6 +121,21 @@ numpydoc_validation_checks : set
 
     The default is an empty set, thus no warnings from docstring validation
     are reported.
+numpydoc_validation_exclude : set
+    A container of strings using :py:mod:`re` syntax specifying patterns to
+    ignore for docstring validation.
+    For example, to skip docstring validation for all objects in
+    ``mypkg.mymodule``::
+
+        numpydoc_validation_exclude = {"mypkg.mymodule."}
+
+    If you wanted to also skip getter methods of ``MyClass``::
+
+        numpydoc_validation_exclude = {"mypkg.mymodule.", "MyClass.get"}
+
+    The default is an empty set meaning no objects are excluded from docstring
+    validation by default.
+    Only has an effect when ``numpydoc_validate = True``.
 numpydoc_edit_link : bool
   .. deprecated:: 0.7.0
 

numpydoc/numpydoc.py

@@ -174,21 +174,26 @@ def mangle_docstrings(app, what, name, obj, options, lines):
             logger.error('[numpydoc] While processing docstring for %r', name)
             raise
 
-        # TODO: validation only applies to non-module docstrings?
         if app.config.numpydoc_validate:
-            # 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"]
-            if {err[0] for err in errors} & app.config.numpydoc_validation_checks:
-                msg = (
-                    f"[numpydoc] Validation warnings while processing "
-                    f"docstring for {name!r}:\n"
-                )
-                for err in errors:
-                    if err[0] in app.config.numpydoc_validation_checks:
-                        msg += f"  {err[0]}: {err[1]}\n"
-                logger.warning(msg)
+            # If the user has supplied patterns to ignore via the
+            # numpydoc_validation_exclude config option, skip validation for
+            # any objs whose name matches any of the patterns
+            excluder = app.config.numpydoc_validation_excluder
+            exclude_from_validation = excluder.search(name) if excluder else False
+            if not exclude_from_validation:
+                # 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"]
+                if {err[0] for err in errors} & app.config.numpydoc_validation_checks:
+                    msg = (
+                        f"[numpydoc] Validation warnings while processing "
+                        f"docstring for {name!r}:\n"
+                    )
+                    for err in errors:
+                        if err[0] in app.config.numpydoc_validation_checks:
+                            msg += f"  {err[0]}: {err[1]}\n"
+                    logger.warning(msg)
 
 
     if (app.config.numpydoc_edit_link and hasattr(obj, '__name__') and
@@ -274,6 +279,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value('numpydoc_xref_ignore', set(), True)
     app.add_config_value('numpydoc_validate', False, True)
     app.add_config_value('numpydoc_validation_checks', set(), True)
+    app.add_config_value('numpydoc_validation_exclude', set(), False)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)
@@ -312,6 +318,19 @@ def update_config(app, config=None):
             f"config value: {invalid_error_codes}"
         )
 
+    # Generate the regexp for docstrings to ignore during validation
+    if isinstance(config.numpydoc_validation_exclude, str):
+        raise ValueError(
+            f"numpydoc_validation_exclude must be a container of strings, "
+            f"e.g. [{config.numpydoc_validation_exclude!r}]."
+        )
+    config.numpydoc_validation_excluder = None
+    if config.numpydoc_validation_exclude:
+        exclude_expr = re.compile(
+            r"|".join(exp for exp in config.numpydoc_validation_exclude)
+        )
+        config.numpydoc_validation_excluder = exclude_expr
+
 
 # ------------------------------------------------------------------------------
 # Docstring-mangling domains

numpydoc/tests/test_docscrape.py

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

numpydoc/tests/test_numpydoc.py

@@ -25,6 +25,8 @@ class MockConfig():
     numpydoc_citation_re = '[a-z0-9_.-]+'
     numpydoc_attributes_as_param_list = True
     numpydoc_validate = False
+    numpydoc_validation_checks = set()
+    numpydoc_validation_exclude = set()
 
 
 class MockBuilder():
@@ -140,6 +142,8 @@ def test_mangle_docstring_validation_warnings(
     # Set up config for test
     app.config.numpydoc_validate = numpydoc_validate
     app.config.numpydoc_validation_checks = numpydoc_validation_checks
+    # Update configuration
+    update_config(app)
     # Set up logging
     status, warning = StringIO(), StringIO()
     logging.setup(app, status, warning)
@@ -153,6 +157,33 @@ def test_mangle_docstring_validation_warnings(
         assert w not in warnings
 
 
+def test_mangle_docstring_validation_exclude():
+    def function_with_bad_docstring():
+        """
+        This docstring will raise docstring validation warnings."""
+    app = MockApp()
+    app.config.numpydoc_validate = True
+    app.config.numpydoc_validation_checks = {"all"}
+    app.config.numpydoc_validation_exclude = [r"_bad_"]
+    # Call update_config to construct regexp from config value
+    update_config(app)
+    # Setup for catching warnings
+    status, warning = StringIO(), StringIO()
+    logging.setup(app, status, warning)
+    # Run mangle docstrings on function_with_bad_docstring
+    mangle_docstrings(
+        app,
+        'function',
+        function_with_bad_docstring.__name__,
+        function_with_bad_docstring,
+        None,
+        function_with_bad_docstring.__doc__.split('\n'),
+    )
+    # Validation is skipped due to exclude pattern matching fn name, therefore
+    # no warnings expected
+    assert warning.getvalue() == ""
+
+
 def test_update_config_invalid_validation_set():
     app = MockApp()
     # Results in {'a', 'l'} instead of {"all"}
@@ -161,6 +192,14 @@ def test_update_config_invalid_validation_set():
         update_config(app)
 
 
+def test_update_config_exclude_str():
+    app = MockApp()
+    app.config.numpydoc_validation_checks = set()
+    app.config.numpydoc_validation_exclude = "shouldnt-be-a-str"
+    with pytest.raises(ValueError, match="\['shouldnt-be-a-str'\]"):
+        update_config(app)
+
+
 if __name__ == "__main__":
     import pytest
     pytest.main()