DOC: Use official numpydoc extension (pandas-dev#24098)

* Use official numpydoc package

 - Replace custom numpydoc in `doc/sphinxext/numpydoc` with official
   numpydoc release
 - Remove `numpydoc_use_blockquotes` parameter

Signed-off-by: Fabian Haase <[email protected]>

* Add numpydoc package to travis

Signed-off-by: Fabian Haase <[email protected]>

* Use member listing for attributes

Signed-off-by: Fabian Haase <[email protected]>

* Move modification of SphinxDocString to conf.py

Signed-off-by: Fabian Haase <[email protected]>

* Update comments to be more descriptive

Signed-off-by: Fabian Haase <[email protected]>

* Fix linting

Signed-off-by: Fabian Haase <[email protected]>

* Review of @jorisvandenbossche

Signed-off-by: Fabian Haase <[email protected]>

* Fix linting

Signed-off-by: Fabian Haase <[email protected]>

Author: FHaase

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',
@@ -91,12 +90,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)]
@@ -411,6 +404,62 @@
 ]
 
 
+def sphinxdocstring_str(self, indent=0, func_role="obj"):
+    # Pandas displays Attributes section in style like Methods section
+
+    # Function is copy of `SphinxDocString.__str__`
+    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(),
+        # Replaced `self._str_param_list('Attributes', fake_autosummary=True)`
+        # with `self._str_member_list('Attributes')`
+        'attributes': self._str_member_list('Attributes'),
+        'methods': self._str_member_list('Methods'),
+    }
+    ns = {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__ = sphinxdocstring_str
+
+
+# Fix "WARNING: Inline strong start-string without end-string."
+# PR #155 "Escape the * in *args and **kwargs" from numpydoc
+# Can be removed after PR merges in v0.9.0
+def decorate_process_param(func):
+    def _escape_args_and_kwargs(name):
+        if name[:2] == '**':
+            return r'\*\*' + name[2:]
+        elif name[:1] == '*':
+            return r'\*' + name[1:]
+        else:
+            return name
+
+    def func_wrapper(self, param, desc, fake_autosummary):
+        param = _escape_args_and_kwargs(param.strip())
+        return func(self, param, desc, fake_autosummary)
+
+    return func_wrapper
+
+
+func = SphinxDocString._process_param
+SphinxDocString._process_param = decorate_process_param(func)
+
 # Add custom Documenter to handle attributes/methods of an AccessorProperty
 # eg pandas.Series.str and pandas.Series.dt (see GH9322)