Use definition lists rather than blockquotes

Make blockquote behaviour optional. Not yet tested

Author: jnothman

doc/install.rst

@@ -20,6 +20,10 @@ The following options can be set in your Sphinx ``conf.py``:
 numpydoc_use_plots : bool
   Whether to produce ``plot::`` directives for Examples sections that
   contain ``import matplotlib``.
+numpydoc_use_blockqutoes : 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_show_class_members : bool
   Whether to show all members of a class in the Methods and Attributes
   sections automatically.

numpydoc/docscrape_sphinx.py

@@ -28,6 +28,7 @@ def __init__(self, docstring, config={}):
 
     def load_config(self, config):
         self.use_plots = config.get('use_plots', False)
+        self.use_blockquotes = config.get('use_blockquotes', False)
         self.class_members_toctree = config.get('class_members_toctree', True)
         self.template = config.get('template', None)
         if self.template is None:
@@ -63,18 +64,26 @@ def _str_extended_summary(self):
         return self['Extended Summary'] + ['']
 
     def _str_returns(self, name='Returns'):
+        if self.use_blockquotes:
+            typed_fmt = '**%s** : %s'
+            untyped_fmt = '**%s**'
+        else:
+            typed_fmt = '%s : %s'
+            untyped_fmt = '%s'
+
         out = []
         if self[name]:
             out += self._str_field_list(name)
             out += ['']
             for param, param_type, desc in self[name]:
                 if param_type:
-                    out += self._str_indent(['**%s** : %s' % (param.strip(),
-                                                              param_type)])
+                    out += self._str_indent([typed_fmt % (param.strip(),
+                                                          param_type)])
                 else:
-                    out += self._str_indent([param.strip()])
+                    out += self._str_indent([untyped_fmt % param.strip()])
                 if desc:
-                    out += ['']
+                    if self.use_blockquotes:
+                        out += ['']
                     out += self._str_indent(desc, 8)
                 out += ['']
         return out
@@ -117,7 +126,7 @@ def _process_param(self, param, desc, autosum):
         relies on Sphinx's plugin mechanism.
         """
         param = param.strip()
-        display_param = '**%s**' % param
+        display_param = ('**%s**' if self.use_blockquotes else '%s') % param
 
         if autosum is None:
             return display_param, desc
@@ -197,7 +206,8 @@ def _str_param_list(self, name, fake_autosummary=False):
                 else:
                     out += self._str_indent([display_param])
                 if desc:
-                    out += ['']  # produces a blockquote, rather than a dt/dd
+                    if self.use_blockquotes:
+                        out += ['']
                     out += self._str_indent(desc, 8)
                 out += ['']
 

numpydoc/numpydoc.py

@@ -65,6 +65,7 @@ def rename_references(app, what, name, obj, options, lines,
 def mangle_docstrings(app, what, name, obj, options, lines):
 
     cfg = {'use_plots': app.config.numpydoc_use_plots,
+           'use_blockquotes': app.config.numpydoc_use_blockquotes,
            'show_class_members': app.config.numpydoc_show_class_members,
            'show_inherited_class_members':
            app.config.numpydoc_show_inherited_class_members,
@@ -131,6 +132,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.connect('autodoc-process-signature', mangle_signature)
     app.add_config_value('numpydoc_edit_link', None, False)
     app.add_config_value('numpydoc_use_plots', None, False)
+    app.add_config_value('numpydoc_use_blockquotes', None, False)
     app.add_config_value('numpydoc_show_class_members', True, True)
     app.add_config_value('numpydoc_show_inherited_class_members', True, True)
     app.add_config_value('numpydoc_class_members_toctree', True, True)

numpydoc/tests/test_docscrape.py

@@ -468,28 +468,24 @@ def test_sphinx_str():
 
 :Parameters:
 
-    **mean** : (N,) ndarray
-
+    mean : (N,) ndarray
         Mean of the N-dimensional distribution.
 
         .. math::
 
            (1+2+3)/3
 
-    **cov** : (N, N) ndarray
-
+    cov : (N, N) ndarray
         Covariance matrix of the distribution.
 
-    **shape** : tuple of ints
-
+    shape : tuple of ints
         Given a shape of, for example, (m,n,k), m*n*k samples are
         generated, and packed in an m-by-n-by-k arrangement.  Because
         each sample is N-dimensional, the output shape is (m,n,k,N).
 
 :Returns:
 
-    **out** : ndarray
-
+    out : ndarray
         The drawn samples, arranged according to `shape`.  If the
         shape given is (m,n,...), then the shape of `out` is is
         (m,n,...,N).
@@ -498,26 +494,22 @@ def test_sphinx_str():
         value drawn from the distribution.
 
     list of str
-
         This is not a real return value.  It exists to test
         anonymous return values.
 
 :Other Parameters:
 
-    **spam** : parrot
-
+    spam : parrot
         A parrot off its mortal coil.
 
 :Raises:
 
-    **RuntimeError**
-
+    RuntimeError
         Some error
 
 :Warns:
 
-    **RuntimeWarning**
-
+    RuntimeWarning
         Some warning
 
 .. warning::
@@ -585,16 +577,13 @@ def test_sphinx_yields_str():
 
 :Yields:
 
-    **a** : int
-
+    a : int
         The number of apples.
 
-    **b** : int
-
+    b : int
         The number of bananas.
 
     int
-
         The number of unknowns.
 """)
 
@@ -1071,12 +1060,10 @@ def no_period(self):
 
     :Parameters:
 
-        **f** : callable ``f(t, y, *f_args)``
-
+        f : callable ``f(t, y, *f_args)``
             Aaa.
 
-        **jac** : callable ``jac(t, y, *jac_args)``
-
+        jac : callable ``jac(t, y, *jac_args)``
             Bbb.
 
     .. rubric:: Examples
@@ -1137,12 +1124,10 @@ def test_templated_sections():
 
     :Parameters:
 
-        **f** : callable ``f(t, y, *f_args)``
-
+        f : callable ``f(t, y, *f_args)``
             Aaa.
 
-        **jac** : callable ``jac(t, y, *jac_args)``
-
+        jac : callable ``jac(t, y, *jac_args)``
             Bbb.
 
     """)