Merge branch 'master' into bold

Author: jnothman

README.rst

@@ -11,16 +11,16 @@
 numpydoc -- Numpy's Sphinx extensions
 =====================================
 
-Numpy's documentation uses several custom extensions to Sphinx.  These
-are shipped in this ``numpydoc`` package, in case you want to make use
-of them in third-party projects.
+This package provides the ``numpydoc`` Sphinx extension for handling
+docstrings formatted according to the `NumPy documentation format
+<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`__.
+The extension also adds the code description directives
+``np:function``, ``np-c:function``, etc.
 
-The ``numpydoc`` extension provides support for the Numpy docstring format in
-Sphinx, and adds the code description directives ``np:function``,
-``np-c:function``, etc.  that support the Numpy docstring syntax.
+For usage information, please refer to the `documentation
+<https://numpydoc.readthedocs.io/>`_.
 
-See `numpydoc docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_
-for how to write docs that use this extension, and the `user guide <https://numpydoc.readthedocs.io>`_
-
-Numpydoc inserts a hook into Sphinx's autodoc that converts docstrings
-following the Numpy/Scipy format to a form palatable to Sphinx.
+The `numpydoc docstring guide
+<https://numpydoc.readthedocs.io/en/latest/format.html>`_ explains how
+to write docs formatted for this extension, and the `user guide
+<https://numpydoc.readthedocs.io>`_ explains how to use it with Sphinx.

doc/install.rst

@@ -9,8 +9,8 @@ The extension is available from:
 * `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
 
 'numpydoc' should be added to the ``extensions`` option in your Sphinx
-``conf.py``.
-
+``conf.py``. (Note that `sphinx.ext.autosummary` will automatically be loaded
+as well.)
 
 Sphinx config options
 =====================
@@ -38,7 +38,7 @@ numpydoc_citation_re : str
   should be mangled to avoid conflicts due to
   duplication across the documentation.  Defaults
   to ``[\w-]+``.
-numpydoc_use_blockqutoes : bool
+numpydoc_use_blockquotes : bool
   Until version 0.8, parameter definitions were shown as blockquotes, rather
   than in a definition list.  If your styling requires blockquotes, switch
   this config option to True.  This option will be removed in version 0.10.

numpydoc/docscrape_sphinx.py

@@ -80,10 +80,11 @@ def _str_returns(self, name='Returns'):
                                                           param_type)])
                 else:
                     out += self._str_indent([untyped_fmt % param.strip()])
-                if desc:
-                    if self.use_blockquotes:
-                        out += ['']
-                    out += self._str_indent(desc, 8)
+                if desc and self.use_blockquotes:
+                    out += ['']
+                elif not desc:
+                    desc = ['..']
+                out += self._str_indent(desc, 8)
                 out += ['']
         return out
 

numpydoc/numpydoc.py

@@ -151,6 +151,8 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_domain(NumpyPythonDomain)
     app.add_domain(NumpyCDomain)
 
+    app.setup_extension('sphinx.ext.autosummary')
+
     metadata = {'version': __version__,
                 'parallel_read_safe': True}
     return metadata

numpydoc/tests/test_docscrape.py

@@ -56,14 +56,15 @@
   -------
   out : ndarray
       The drawn samples, arranged according to `shape`.  If the
-      shape given is (m,n,...), then the shape of `out` is is
+      shape given is (m,n,...), then the shape of `out` is
       (m,n,...,N).
 
       In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
       value drawn from the distribution.
   list of str
       This is not a real return value.  It exists to test
       anonymous return values.
+  no_description
 
   Other Parameters
   ----------------
@@ -184,7 +185,7 @@ def test_other_parameters():
 
 
 def test_returns():
-    assert_equal(len(doc['Returns']), 2)
+    assert_equal(len(doc['Returns']), 3)
     arg, arg_type, desc = doc['Returns'][0]
     assert_equal(arg, 'out')
     assert_equal(arg_type, 'ndarray')
@@ -197,6 +198,11 @@ def test_returns():
     assert desc[0].startswith('This is not a real')
     assert desc[-1].endswith('anonymous return values.')
 
+    arg, arg_type, desc = doc['Returns'][2]
+    assert_equal(arg, 'no_description')
+    assert_equal(arg_type, '')
+    assert not ''.join(desc).strip()
+
 
 def test_yields():
     section = doc_yields['Yields']
@@ -365,14 +371,15 @@ def test_str():
 -------
 out : ndarray
     The drawn samples, arranged according to `shape`.  If the
-    shape given is (m,n,...), then the shape of `out` is is
+    shape given is (m,n,...), then the shape of `out` is
     (m,n,...,N).
 
     In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
     value drawn from the distribution.
 list of str
     This is not a real return value.  It exists to test
     anonymous return values.
+no_description
 
 Other Parameters
 ----------------
@@ -496,7 +503,7 @@ def test_sphinx_str():
 
     **out** : ndarray
         The drawn samples, arranged according to `shape`.  If the
-        shape given is (m,n,...), then the shape of `out` is is
+        shape given is (m,n,...), then the shape of `out` is
         (m,n,...,N).
 
         In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
@@ -506,6 +513,9 @@ def test_sphinx_str():
         This is not a real return value.  It exists to test
         anonymous return values.
 
+    no_description
+        ..
+
 :Other Parameters:
 
     **spam** : parrot