Command-line tool to help debug NumpyDocString

doc/index.rst

@@ -22,3 +22,4 @@ Documentation
     install
     format
     example
+    validation

doc/validation.rst

@@ -0,0 +1,12 @@
+==============================
+Validating NumpyDoc docstrings
+==============================
+
+One tool for validating docstrings is to see how an object's dosctring
+translates to Restructured Text.  Using numpydoc as a command-line tool
+facilitates this. For example to see the Restructured Text generated
+for ``numpy.ndarray``, use:
+
+.. code-block:: bash
+
+    $ python -m numpydoc numpy.ndarray

numpydoc/__main__.py

@@ -0,0 +1,44 @@
+import argparse
+import importlib
+import ast
+
+from .docscrape_sphinx import get_doc_object
+
+
+def main(argv=None):
+    """Test numpydoc docstring generation for a given object"""
+
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument('import_path', help='e.g. numpy.ndarray')
+
+    def _parse_config(s):
+        key, _, value = s.partition('=')
+        value = ast.literal_eval(value)
+        return key, value
+
+    ap.add_argument('-c', '--config', type=_parse_config,
+                    action='append',
+                    help='key=val where val will be parsed by literal_eval, '
+                         'e.g. -c use_plots=True. Multiple -c can be used.')
+    args = ap.parse_args(argv)
+
+    parts = args.import_path.split('.')
+
+    for split_point in range(len(parts), 0, -1)[::-1]:
+        try:
+            path = '.'.join(parts[:split_point])
+            obj = importlib.import_module(path)
+        except ImportError:
+            continue
+        break
+    else:
+        raise ImportError('Could not resolve {!r} to an importable object'
+                          ''.format(args.import_path))
+
+    for part in parts[split_point:]:
+        obj = getattr(obj, part)
+
+    print(get_doc_object(obj, config=dict(args.config or [])))
+
+if __name__ == '__main__':
+    main()

numpydoc/tests/test_main.py

@@ -0,0 +1,15 @@
+from numpydoc.__main__ import main
+
+import sys
+try:
+    from StringIO import StringIO
+except ImportError:
+    from io import StringIO
+
+
+def test_main():
+    f = StringIO()
+    sys.stdout, old_stdout = f, sys.stdout
+    main(['numpydoc.__main__.main'])
+    assert f.getvalue().strip() == main.__doc__
+    sys.stdout = old_stdout