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