Add mechanism for validation check selection.

Adds a config option with a set to allow users to select
which validation checks are used. Default is an empty set,
which means none of the validation checks raise warnings
during the build process.

Add documentation for new option and activate in the doc build.

Author: rossbar

doc/conf.py

@@ -84,7 +84,11 @@
 version = re.sub(r'(\.dev\d+).*?$', r'\1', version)
 numpydoc_xref_param_type = True
 numpydoc_xref_ignore = {'optional', 'type_without_description', 'BadException'}
+# Run docstring validation as part of build process
 numpydoc_validate = True
+# Report warnings from all build-in validation checks
+from numpydoc.validate import ERROR_MSGS
+numpydoc_validation_checks = set(ERROR_MSGS.keys())
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/install.rst

@@ -99,6 +99,11 @@ numpydoc_xref_ignore : set or ``"all"``
 numpydoc_validate : bool
     Whether or not to run docstring validation during the sphinx-build process.
     Default is ``False``.
+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.
 numpydoc_edit_link : bool
   .. deprecated:: 0.7.0
 

doc/validation.rst

@@ -15,3 +15,19 @@ For an exhaustive validation of the formatting of the docstring, use the
 ``--validate`` parameter. This will report the errors detected, such as
 incorrect capitalization, wrong order of the sections, and many other
 issues.
+
+Built-in Validation Checks
+--------------------------
+
+The `~numpydoc.validation` module provides a mapping with all of the checks
+that are run as part of the validation procedure.
+The mapping is of the form: ``error_code : <explanation>`` where ``error_code``
+provides a shorthand for the check being run, and ``<explanation>`` provides
+a more detailed message. For example::
+
+    "EX01" : "No examples section found"
+
+The full mapping of validation checks is given below.
+
+.. literalinclude:: ../numpydoc/validate.py
+   :lines: 36-90

numpydoc/numpydoc.py

@@ -176,9 +176,14 @@ def mangle_docstrings(app, what, name, obj, options, lines):
 
         # 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"]
             for err in errors:
-                logger.warning(err)
+                # err[0] = error code
+                if err[0] in app.config.numpydoc_validation_checks:
+                    logger.warning(err)
 
 
     if (app.config.numpydoc_edit_link and hasattr(obj, '__name__') and
@@ -263,6 +268,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value('numpydoc_xref_aliases', dict(), True)
     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)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)