Add all keyword to validation_check configuration.

More flexibility in configuring which validation checks to run during
sphinx build. If 'all' is present, treat the rest of the set as a
blocklist, else an allowlist.

Author: rossbar

doc/conf.py

@@ -86,18 +86,7 @@
 numpydoc_xref_ignore = {'optional', 'type_without_description', 'BadException'}
 # Run docstring validation as part of build process
 numpydoc_validate = True
-numpydoc_validation_checks = {
-    "GL06",  # Unknown section name
-    "GL07",  # Sections in wrong order
-    "GL08",  # Object missing docstring
-    "PR01",  # Missing parameters
-    "PR02",  # Unknown parameters
-    "PR03",  # Incorrect parameter ordering
-    "PR10",  # Missing colon between parameter name and type
-    "RT01",  # No returns section
-    "SA01",  # Missing See Also section
-    "EX01",  # Missing Examples section
-}
+numpydoc_validation_checks = {"all", "GL01", "SA04", "RT03"}
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/install.rst

@@ -102,8 +102,25 @@ numpydoc_validate : bool
 numpydoc_validation_checks : set
     The set of validation checks to report during the sphinx build process.
     Only has an effect when ``numpydoc_validate = True``.
-    By default, report warnings from all the validation checks provided by the
-    :doc:`validation` module.
+    If ``"all"`` is in the set, then the results of all of the
+    :ref:`built-in validation checks <validation_checks>` are reported.
+    If the set includes ``"all"`` and additional error codes, then all
+    validation checks *except* the listed error codes will be run.
+    If the set contains *only* individual error codes, then only those checks
+    will be run.
+    For example::
+
+        # Report warnings for all validation checks
+        numpydoc_validation_checks = {"all"}
+
+        # Report warnings for all checks *except* for GL01, GL02, and GL05
+        numpydoc_validation_checks = {"all", "GL01", "GL02", "GL05"}
+
+        # Only report warnings for the SA01 and EX01 checks
+        numpydoc_validation_checks = {"SA01", "EX01"}
+
+    The default is an empty set, thus no warnings from docstring validation
+    are reported.
 numpydoc_edit_link : bool
   .. deprecated:: 0.7.0
 

doc/validation.rst

@@ -16,6 +16,8 @@ For an exhaustive validation of the formatting of the docstring, use the
 incorrect capitalization, wrong order of the sections, and many other
 issues.
 
+.. _validation_checks:
+
 Built-in Validation Checks
 --------------------------
 

numpydoc/numpydoc.py

@@ -34,7 +34,7 @@
     raise RuntimeError("Sphinx 1.6.5 or newer is required")
 
 from .docscrape_sphinx import get_doc_object
-from .validate import validate
+from .validate import validate, ERROR_MSGS
 from .xref import DEFAULT_LINKS
 from . import __version__
 
@@ -298,6 +298,12 @@ def update_config(app, config=None):
             numpydoc_xref_aliases_complete[key] = value
     config.numpydoc_xref_aliases_complete = numpydoc_xref_aliases_complete
 
+    # Processing to determine whether numpydoc_validation_checks is treated
+    # as a blocklist or allowlist
+    if "all" in config.numpydoc_validation_checks:
+        block = deepcopy(config.numpydoc_validation_checks)
+        config.numpydoc_validation_checks = set(ERROR_MSGS.keys()) - block
+
 
 # ------------------------------------------------------------------------------
 # Docstring-mangling domains