DOC: Use official numpydoc extension

ci/deps/travis-36-doc.yaml

@@ -21,6 +21,7 @@ dependencies:
   - notebook
   - numexpr
   - numpy=1.13*
+  - numpydoc
   - openpyxl
   - pandoc
   - pyarrow

doc/source/conf.py

@@ -18,7 +18,10 @@
 import importlib
 import logging
 import warnings
+
 from sphinx.ext.autosummary import _import_by_name
+from numpydoc.docscrape import NumpyDocString
+from numpydoc.docscrape_sphinx import SphinxDocString
 
 logger = logging.getLogger(__name__)
 
@@ -49,10 +52,6 @@
 
 ])
 
-# numpydoc is available in the sphinxext directory, and can't be imported
-# until sphinxext is available in the Python path
-from numpydoc.docscrape import NumpyDocString
-
 # -- General configuration -----------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -64,7 +63,7 @@
               'sphinx.ext.doctest',
               'sphinx.ext.extlinks',
               'sphinx.ext.todo',
-              'numpydoc',
+              'numpydoc',  # handle NumPy documentation formatted docstrings
               'IPython.sphinxext.ipython_directive',
               'IPython.sphinxext.ipython_console_highlighting',
               'matplotlib.sphinxext.plot_directive',
@@ -102,12 +101,6 @@
 if any(re.match(r"\s*api\s*", l) for l in index_rst_lines):
     autosummary_generate = True
 
-# numpydoc
-# for now use old parameter listing (styling + **kwargs problem)
-numpydoc_use_blockquotes = True
-# use member listing for attributes
-numpydoc_attributes_as_param_list = False
-
 # matplotlib plot directive
 plot_include_source = True
 plot_formats = [("png", 90)]
@@ -420,6 +413,36 @@
 ]
 
 
+# Modify numpydoc to show Attributes section like Methods section
+# PANDAS HACK: Replace attributes param_list by member_list
+def alternative_str(self, indent=0, func_role="obj"):
+    ns = {
+        'signature': self._str_signature(),
+        'index': self._str_index(),
+        'summary': self._str_summary(),
+        'extended_summary': self._str_extended_summary(),
+        'parameters': self._str_param_list('Parameters'),
+        'returns': self._str_returns('Returns'),
+        'yields': self._str_returns('Yields'),
+        'other_parameters': self._str_param_list('Other Parameters'),
+        'raises': self._str_param_list('Raises'),
+        'warns': self._str_param_list('Warns'),
+        'warnings': self._str_warnings(),
+        'see_also': self._str_see_also(func_role),
+        'notes': self._str_section('Notes'),
+        'references': self._str_references(),
+        'examples': self._str_examples(),
+        'attributes': self._str_member_list('Attributes'),
+        'methods': self._str_member_list('Methods'),
+    }
+    ns = dict((k, '\n'.join(v)) for k, v in ns.items())
+
+    rendered = self.template.render(**ns)
+    return '\n'.join(self._str_indent(rendered.split('\n'), indent))
+
+
+SphinxDocString.__str__ = alternative_str
+
 # Add custom Documenter to handle attributes/methods of an AccessorProperty
 # eg pandas.Series.str and pandas.Series.dt (see GH9322)