Activate validation during sphinx-build.

Add a conf option to turn on/off.

TODO: test

Author: rossbar

doc/conf.py

@@ -84,6 +84,7 @@
 version = re.sub(r'(\.dev\d+).*?$', r'\1', version)
 numpydoc_xref_param_type = True
 numpydoc_xref_ignore = {'optional', 'type_without_description', 'BadException'}
+numpydoc_validate = True
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

numpydoc/numpydoc.py

@@ -34,6 +34,7 @@
     raise RuntimeError("Sphinx 1.6.5 or newer is required")
 
 from .docscrape_sphinx import get_doc_object
+from .validate import validate
 from .xref import DEFAULT_LINKS
 from . import __version__
 
@@ -173,6 +174,13 @@ 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:
+            errors = validate(doc)["errors"]
+            for err in errors:
+                logger.warn(err)
+
+
     if (app.config.numpydoc_edit_link and hasattr(obj, '__name__') and
             obj.__name__):
         if hasattr(obj, '__module__'):
@@ -254,6 +262,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value('numpydoc_xref_param_type', False, True)
     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)
 
     # Extra mangling domains
     app.add_domain(NumpyPythonDomain)

numpydoc/tests/test_numpydoc.py

@@ -19,6 +19,7 @@ class MockConfig():
     numpydoc_edit_link = False
     numpydoc_citation_re = '[a-z0-9_.-]+'
     numpydoc_attributes_as_param_list = True
+    numpydoc_validate = False
 
 
 class MockBuilder():

numpydoc/tests/tinybuild/conf.py

@@ -22,3 +22,4 @@
 highlight_language = 'python3'
 numpydoc_class_members_toctree = False
 numpydoc_xref_param_type = True
+numpydoc_validate = True

numpydoc/validate.py

@@ -470,8 +470,10 @@ def validate(obj_name):
     they are validated, are not documented more than in the source code of this
     function.
     """
-    obj = Validator._load_obj(obj_name)
-    doc = Validator(get_doc_object(obj))
+    if isinstance(obj_name, str):
+        doc = Validator(get_doc_object(Validator._load_obj(obj_name)))
+    else:
+        doc = Validator(obj_name)
 
     errs = []
     if not doc.raw_doc: