Merge pull request #107 from jnothman/deflist

Use definition lists rather than blockquotes

Author: pv

doc/install.rst

@@ -38,6 +38,10 @@ numpydoc_citation_re : str
   should be mangled to avoid conflicts due to
   duplication across the documentation.  Defaults
   to ``[\w-]+``.
+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_edit_link : bool
   .. deprecated:: edit your HTML template instead
 

numpydoc/docscrape.py

@@ -13,6 +13,15 @@
 import sys
 
 
+def strip_blank_lines(l):
+    "Remove leading and trailing blank lines from a list of lines"
+    while l and not l[0].strip():
+        del l[0]
+    while l and not l[-1].strip():
+        del l[-1]
+    return l
+
+
 class Reader(object):
     """A line-based string reader.
 
@@ -214,6 +223,7 @@ def _parse_param_list(self, content):
 
             desc = r.read_to_next_unindented_line()
             desc = dedent_lines(desc)
+            desc = strip_blank_lines(desc)
 
             params.append((arg_name, arg_type, desc))
 
@@ -404,7 +414,8 @@ def _str_param_list(self, name):
                     out += ['%s : %s' % (param, param_type)]
                 else:
                     out += [param]
-                out += self._str_indent(desc)
+                if desc and ''.join(desc).strip():
+                    out += self._str_indent(desc)
             out += ['']
         return out
 

numpydoc/docscrape_sphinx.py

@@ -31,6 +31,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:
@@ -66,18 +67,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, fake_autosummary):
         relies on Sphinx's plugin mechanism.
         """
         param = param.strip()
-        display_param = '**%s**' % param
+        display_param = ('**%s**' if self.use_blockquotes else '%s') % param
 
         if not fake_autosummary:
             return display_param, desc
@@ -192,7 +201,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 += ['']
 
@@ -262,7 +272,6 @@ def _str_section(self, name):
         out = []
         if self[name]:
             out += self._str_header(name)
-            out += ['']
             content = textwrap.dedent("\n".join(self[name])).split("\n")
             out += content
             out += ['']
@@ -281,6 +290,7 @@ def _str_warnings(self):
         if self['Warnings']:
             out = ['.. warning::', '']
             out += self._str_indent(self['Warnings'])
+            out += ['']
         return out
 
     def _str_index(self):
@@ -297,6 +307,7 @@ def _str_index(self):
                 out += ['   single: %s' % (', '.join(references))]
             else:
                 out += ['   %s: %s' % (section, ','.join(references))]
+        out += ['']
         return out
 
     def _str_references(self):

numpydoc/numpydoc.py

@@ -71,6 +71,7 @@ def mangle_docstrings(app, what, name, obj, options, lines):
         return
 
     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,
@@ -139,6 +140,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)