Merge branch 'master' into reference-re

Author: jnothman

.travis.yml

@@ -17,13 +17,13 @@ cache:
 before_install:
   - sudo apt-get install texlive texlive-latex-extra latexmk
   - pip install --upgrade pip setuptools  # Upgrade pip and setuptools to get ones with `wheel` support
-  - pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --trusted-host wheels.astropy.org --trusted-host wheels2.astropy.org --use-wheel nose numpy matplotlib ${SPHINX_SPEC}
+  - pip install pytest numpy matplotlib ${SPHINX_SPEC}
 script:
   - |
     python setup.py sdist
     cd dist
     pip install numpydoc* -v
-  - nosetests numpydoc
+  - pytest --pyargs numpydoc
   - |
     cd ../doc
     make SPHINXOPTS=$SPHINXOPTS html

doc/example.py

@@ -93,7 +93,7 @@ def foo(var1, var2, long_var_name='hi'):
 
     .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
 
-    And even use a greek symbol like :math:`omega` inline.
+    And even use a Greek symbol like :math:`\omega` inline.
 
     References
     ----------

doc/format.rst

@@ -119,6 +119,8 @@ The sections of a function's docstring are:
 
      """
 
+.. highlight:: rst
+
 2. **Deprecation warning**
 
    A section (use if applicable) to warn users that the object is deprecated.
@@ -276,46 +278,46 @@ The sections of a function's docstring are:
 
 10. **Warnings**
 
-   An optional section with cautions to the user in free text/reST.
+    An optional section with cautions to the user in free text/reST.
 
 11. **See Also**
 
-   An optional section used to refer to related code.  This section
-   can be very useful, but should be used judiciously.  The goal is to
-   direct users to other functions they may not be aware of, or have
-   easy means of discovering (by looking at the module docstring, for
-   example).  Routines whose docstrings further explain parameters
-   used by this function are good candidates.
+    An optional section used to refer to related code.  This section
+    can be very useful, but should be used judiciously.  The goal is to
+    direct users to other functions they may not be aware of, or have
+    easy means of discovering (by looking at the module docstring, for
+    example).  Routines whose docstrings further explain parameters
+    used by this function are good candidates.
 
-   As an example, for ``numpy.mean`` we would have::
+    As an example, for ``numpy.mean`` we would have::
 
-     See Also
-     --------
-     average : Weighted average
+      See Also
+      --------
+      average : Weighted average
 
-   When referring to functions in the same sub-module, no prefix is
-   needed, and the tree is searched upwards for a match.
+    When referring to functions in the same sub-module, no prefix is
+    needed, and the tree is searched upwards for a match.
 
-   Prefix functions from other sub-modules appropriately.  E.g.,
-   whilst documenting the ``random`` module, refer to a function in
-   ``fft`` by
+    Prefix functions from other sub-modules appropriately.  E.g.,
+    whilst documenting the ``random`` module, refer to a function in
+    ``fft`` by
 
-   ::
+    ::
 
-     fft.fft2 : 2-D fast discrete Fourier transform
+      fft.fft2 : 2-D fast discrete Fourier transform
 
-   When referring to an entirely different module::
+    When referring to an entirely different module::
 
-     scipy.random.norm : Random variates, PDFs, etc.
+      scipy.random.norm : Random variates, PDFs, etc.
 
-   Functions may be listed without descriptions, and this is
-   preferable if the functionality is clear from the function name::
+    Functions may be listed without descriptions, and this is
+    preferable if the functionality is clear from the function name::
 
-     See Also
-     --------
-     func_a : Function a with its description.
-     func_b, func_c_, func_d
-     func_e
+      See Also
+      --------
+      func_a : Function a with its description.
+      func_b, func_c_, func_d
+      func_e
 
 12. **Notes**
 
@@ -393,6 +395,8 @@ The sections of a function's docstring are:
         docstring, the table markup will be broken by numpydoc processing.  See
         `numpydoc issue #130 <https://github.com/numpy/numpydoc/issues/130>`_
 
+.. highlight:: pycon
+
 14. **Examples**
 
     An optional section for examples, using the `doctest
@@ -464,6 +468,7 @@ The sections of a function's docstring are:
     `matplotlib.sphinxext.plot_directive` is loaded as a Sphinx extension in
     ``conf.py``.
 
+.. highlight:: rst
 
 Documenting classes
 -------------------
@@ -501,7 +506,9 @@ In general, it is not necessary to list class methods.  Those that are
 not part of the public API have names that start with an underscore.
 In some cases, however, a class may have a great many methods, of
 which only a few are relevant (e.g., subclasses of ndarray).  Then, it
-becomes useful to have an additional **Methods** section::
+becomes useful to have an additional **Methods** section:
+
+.. code-block:: python
 
   class Photo(ndarray):
       """

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):
+        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/docscrape.py

@@ -8,7 +8,11 @@
 import re
 import pydoc
 from warnings import warn
-import collections
+from collections import namedtuple
+try:
+    from collections.abc import Callable, Mapping
+except ImportError:
+    from collections import Callable, Mapping
 import copy
 import sys
 
@@ -106,7 +110,10 @@ def __str__(self):
         return message
 
 
-class NumpyDocString(collections.Mapping):
+Parameter = namedtuple('Parameter', ['name', 'type', 'desc'])
+
+
+class NumpyDocString(Mapping):
     """Parses a numpydoc string to an abstract representation
 
     Instances define a mapping from section title to structured data.
@@ -225,7 +232,7 @@ def _parse_param_list(self, content):
             desc = dedent_lines(desc)
             desc = strip_blank_lines(desc)
 
-            params.append((arg_name, arg_type, desc))
+            params.append(Parameter(arg_name, arg_type, desc))
 
         return params
 
@@ -317,7 +324,8 @@ def _parse_summary(self):
         while True:
             summary = self._doc.read_to_next_empty_line()
             summary_str = " ".join([s.strip() for s in summary]).strip()
-            if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str):
+            compiled = re.compile(r'^([\w., ]+=)?\s*[\w\.]+\(.*\)$')
+            if compiled.match(summary_str):
                 self['Signature'] = summary_str
                 if not self._is_at_section():
                     continue
@@ -389,7 +397,7 @@ def _str_indent(self, doc, indent=4):
 
     def _str_signature(self):
         if self['Signature']:
-            return [self['Signature'].replace('*', '\*')] + ['']
+            return [self['Signature'].replace('*', r'\*')] + ['']
         else:
             return ['']
 
@@ -409,13 +417,13 @@ def _str_param_list(self, name):
         out = []
         if self[name]:
             out += self._str_header(name)
-            for param, param_type, desc in self[name]:
-                if param_type:
-                    out += ['%s : %s' % (param, param_type)]
+            for param in self[name]:
+                if param.type:
+                    out += ['%s : %s' % (param.name, param.type)]
                 else:
-                    out += [param]
-                if desc and ''.join(desc).strip():
-                    out += self._str_indent(desc)
+                    out += [param.name]
+                if param.desc and ''.join(param.desc).strip():
+                    out += self._str_indent(param.desc)
             out += ['']
         return out
 
@@ -521,7 +529,7 @@ def __init__(self, func, role='func', doc=None, config={}):
                     else:
                         argspec = inspect.getargspec(func)
                     signature = inspect.formatargspec(*argspec)
-                signature = '%s%s' % (func_name, signature.replace('*', '\*'))
+                signature = '%s%s' % (func_name, signature.replace('*', r'\*'))
             except TypeError:
                 signature = '%s()' % func_name
             self['Signature'] = signature
@@ -538,7 +546,7 @@ def __str__(self):
         out = ''
 
         func, func_name = self.get_func()
-        signature = self['Signature'].replace('*', '\*')
+        signature = self['Signature'].replace('*', r'\*')
 
         roles = {'func': 'function',
                  'meth': 'method'}
@@ -591,7 +599,8 @@ def splitlines_x(s):
                     for name in sorted(items):
                         try:
                             doc_item = pydoc.getdoc(getattr(self._cls, name))
-                            doc_list.append((name, '', splitlines_x(doc_item)))
+                            doc_list.append(
+                                Parameter(name, '', splitlines_x(doc_item)))
                         except AttributeError:
                             pass  # method doesn't exist
                     self[field] = doc_list
@@ -603,7 +612,7 @@ def methods(self):
         return [name for name, func in inspect.getmembers(self._cls)
                 if ((not name.startswith('_')
                      or name in self.extra_public_methods)
-                    and isinstance(func, collections.Callable)
+                    and isinstance(func, Callable)
                     and self._is_show_member(name))]
 
     @property