More docs

numpydoc/docscrape_sphinx.py

@@ -89,7 +89,8 @@ def _process_param(self, param, desc, autosum):
  param : str
  The name of the parameter
  desc : list of str
- The parameter description as given in the docstring
+ The parameter description as given in the docstring. This is
+ ignored when autosummary logic applies.
  autosum : list or None
  If a list, autosummary-style behaviour will apply for params
  that are attributes of the class and have a docstring.
@@ -152,6 +153,25 @@ def _process_param(self, param, desc, autosum):
  return display_param, desc
 
  def _str_param_list(self, name, fake_autosummary=False):
+ """Generate RST for a listing of parameters or similar
+
+ Parameter names are displayed as bold text, and descriptions
+ are in blockquotes. Descriptions may therefore contain block
+ markup as well.
+
+ Parameters
+ ----------
+ name : str
+ Section name (e.g. Parameters)
+ fake_autosummary : bool
+ When True, the parameter names may correspond to attributes of the
+ object beign documented, usually ``property`` instances on a class.
+ In this case, names will be linked to fuller descriptions.
+
+ Returns
+ -------
+ rst : list of str
+ """
  out = []
  if self[name]:
  if fake_autosummary:
@@ -170,7 +190,7 @@ def _str_param_list(self, name, fake_autosummary=False):
  else:
  out += self._str_indent([display_param])
  if desc:
- out += ['']
+ out += [''] # produces a blockquote, rather than a dt/dd
  out += self._str_indent(desc, 8)
  out += ['']