feat(numpydoc.py): Added config option numpydoc_validation_exclude_files for Sphinx plugin

Uses very similar regex processing to `numpydoc_validation_exclude` but instead applies to a module check before any numpydoc validation is performed.

Author: mattgebert

numpydoc/numpydoc.py

@@ -27,6 +27,7 @@
 
 from docutils.nodes import Text, citation, comment, inline, reference, section
 from sphinx.addnodes import desc_content, pending_xref
+from sphinx.application import Sphinx as SphinxApp
 from sphinx.util import logging
 
 from . import __version__
@@ -52,7 +53,7 @@ def _traverse_or_findall(node, condition, **kwargs):
     )
 
 
-def rename_references(app, what, name, obj, options, lines):
+def rename_references(app: SphinxApp, what, name, obj, options, lines):
     # decorate reference numbers so that there are no duplicates
     # these are later undecorated in the doctree, in relabel_references
     references = set()
@@ -114,7 +115,7 @@ def is_docstring_section(node):
     return False
 
 
-def relabel_references(app, doc):
+def relabel_references(app: SphinxApp, doc):
     # Change 'hash-ref' to 'ref' in label text
     for citation_node in _traverse_or_findall(doc, citation):
         if not _is_cite_in_numpydoc_docstring(citation_node):
@@ -141,7 +142,7 @@ def matching_pending_xref(node):
             ref.replace(ref_text, new_text.copy())
 
 
-def clean_backrefs(app, doc, docname):
+def clean_backrefs(app: SphinxApp, doc, docname):
     # only::latex directive has resulted in citation backrefs without reference
     known_ref_ids = set()
     for ref in _traverse_or_findall(doc, reference, descend=True):
@@ -161,7 +162,7 @@ def clean_backrefs(app, doc, docname):
 DEDUPLICATION_TAG = "    !! processed by numpydoc !!"
 
 
-def mangle_docstrings(app, what, name, obj, options, lines):
+def mangle_docstrings(app: SphinxApp, what, name, obj, options, lines):
     if DEDUPLICATION_TAG in lines:
         return
     show_inherited_class_members = app.config.numpydoc_show_inherited_class_members
@@ -190,6 +191,19 @@ def mangle_docstrings(app, what, name, obj, options, lines):
         title_re = re.compile(pattern, re.IGNORECASE | re.DOTALL)
         lines[:] = title_re.sub("", u_NL.join(lines)).split(u_NL)
     else:
+        # Test the obj to find the module path, and skip the check if it's path is matched by
+        # numpydoc_validation_exclude_files
+        if app.config.numpydoc_validation_exclude_files:
+            excluder = app.config.numpydoc_validation_files_excluder
+            module = getattr(obj, "__module__", None)
+            if module:
+                # Perform the exclusion check solely on the module if there's no __path__.
+                path = getattr(obj, "__path__", module)
+                exclude_from_validation = excluder.search(path) if excluder else False
+                if exclude_from_validation:
+                    # Skip validation for this object.
+                    return
+
         try:
             doc = get_doc_object(
                 obj, what, u_NL.join(lines), config=cfg, builder=app.builder
@@ -239,7 +253,7 @@ def mangle_docstrings(app, what, name, obj, options, lines):
     lines += ["..", DEDUPLICATION_TAG]
 
 
-def mangle_signature(app, what, name, obj, options, sig, retann):
+def mangle_signature(app: SphinxApp, what, name, obj, options, sig, retann):
     # Do not try to inspect classes that don't define `__init__`
     if inspect.isclass(obj) and (
         not hasattr(obj, "__init__")
@@ -273,7 +287,7 @@ def _clean_text_signature(sig):
     return start_sig + sig + ")"
 
 
-def setup(app, get_doc_object_=get_doc_object):
+def setup(app: SphinxApp, get_doc_object_=get_doc_object):
     if not hasattr(app, "add_config_value"):
         return None  # probably called by nose, better bail out
 
@@ -299,6 +313,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value("numpydoc_xref_ignore", set(), True, types=[set, str])
     app.add_config_value("numpydoc_validation_checks", set(), True)
     app.add_config_value("numpydoc_validation_exclude", set(), False)
+    app.add_config_value("numpydoc_validation_exclude_files", set(), False)
     app.add_config_value("numpydoc_validation_overrides", dict(), False)
 
     # Extra mangling domains
@@ -309,7 +324,7 @@ def setup(app, get_doc_object_=get_doc_object):
     return metadata
 
 
-def update_config(app, config=None):
+def update_config(app: SphinxApp, config=None):
     """Update the configuration with default values."""
     if config is None:  # needed for testing and old Sphinx
         config = app.config
@@ -342,6 +357,21 @@ def update_config(app, config=None):
         )
         config.numpydoc_validation_excluder = exclude_expr
 
+    # Generate the regexp for files to ignore during validation
+    if isinstance(config.numpydoc_validation_exclude_files, str):
+        raise ValueError(
+            f"numpydoc_validation_exclude_files must be a container of strings, "
+            f"e.g. [{config.numpydoc_validation_exclude_files!r}]."
+        )
+
+    config.numpydoc_validation_files_excluder = None
+    if config.numpydoc_validation_exclude_files:
+        exclude_files_expr = re.compile(
+            r"|".join(exp for exp in config.numpydoc_validation_exclude_files)
+        )
+        config.numpydoc_validation_files_excluder = exclude_files_expr
+
+    # Generate the regexp for validation overrides
     for check, patterns in config.numpydoc_validation_overrides.items():
         config.numpydoc_validation_overrides[check] = re.compile(
             r"|".join(exp for exp in patterns)

numpydoc/tests/test_docscrape.py

@@ -1593,6 +1593,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_exclude_files = set()
             self.numpydoc_validation_overrides = dict()
 
     xref_aliases_complete = deepcopy(DEFAULT_LINKS)

numpydoc/tests/test_numpydoc.py

@@ -31,6 +31,7 @@ class MockConfig:
     numpydoc_attributes_as_param_list = True
     numpydoc_validation_checks = set()
     numpydoc_validation_exclude = set()
+    numpydoc_validation_exclude_files = set()
     numpydoc_validation_overrides = dict()
 
 
@@ -287,6 +288,62 @@ def test_clean_backrefs():
     assert "id1" in citation["backrefs"]
 
 
+@pytest.mark.parametrize(
+    "exclude_files, has_warnings",
+    [
+        (
+            [
+                r"^doesnt_match_any_file$",
+            ],
+            True,
+        ),
+        (
+            [
+                r"^test_numpydoc$",
+            ],
+            False,
+        ),
+    ],
+)
+def test_mangle_skip_exclude_files(exclude_files, has_warnings):
+    """
+    Check that the regex expressions in numpydoc_validation_files_exclude
+    are correctly used to skip checks on files that match the patterns.
+    """
+
+    def process_something_noop_function():
+        """Process something."""
+
+    app = MockApp()
+    app.config.numpydoc_validation_checks = {"all"}
+
+    # Class attributes for config persist - need to reset them to unprocessed states.
+    app.config.numpydoc_validation_exclude = set()  # Reset to default...
+    app.config.numpydoc_validation_overrides = dict()  # Reset to default...
+
+    app.config.numpydoc_validation_exclude_files = exclude_files
+    update_config(app)
+
+    # Setup for catching warnings
+    status, warning = StringIO(), StringIO()
+    logging.setup(app, status, warning)
+
+    # Simulate a file that matches the exclude pattern
+    docname = "test_numpydoc"
+    mangle_docstrings(
+        app,
+        "function",
+        process_something_noop_function.__name__,
+        process_something_noop_function,
+        None,
+        process_something_noop_function.__doc__.split("\n"),
+    )
+
+    # Are warnings generated?
+    print(warning.getvalue())
+    assert bool(warning.getvalue()) is has_warnings
+
+
 if __name__ == "__main__":
     import pytest