Prepend matplotlib summary to proplot method docstrings

proplot-dev · lukelbd · Sep 17, 2019 · Sep 17, 2019 · Sep 17, 2019 · Sep 17, 2019
commit 93c640566d856a288907d39e1c26f6616d13c110
diff --git a/proplot/axes.py b/proplot/axes.py
@@ -101,18 +101,21 @@ def _concatenate_axes_docstrings(func):
     """Concatenates docstrings from a matplotlib axes method with a ProPlot
     axes method. Requires that proplot documentation has no other parameters,
     notes, or examples sections."""
-    if rc.get('docstring.hardcopy'): # True when running sphinx
-        return func
     # Get matplotlib axes func
     # If current func has no docstring just blindly copy matplotlib one
     name = func.__name__
     orig = getattr(maxes.Axes, name)
     odoc = inspect.getdoc(orig)
     if not odoc: # should never happen
         return func
-    fdoc = inspect.getdoc(func) # also dedents
-    if not fdoc:
-        func.__doc__ = odoc
+
+    # Prepend summary and potentially bail
+    # TODO: Does this break anything on sphinx website?
+    fdoc = inspect.getdoc(func) or '' # also dedents
+    summary = odoc[:re.search('\.( | *\n|\Z)', odoc).start() + 1]
+    fdoc = f'{summary}\n\n{fdoc}'
+    if rc.get('docstring.hardcopy'): # True when running sphinx
+        func.__doc__ = fdoc
         return func
 
     # Obfuscate signature by converting to *args **kwargs. Note this does
@@ -126,7 +129,7 @@ def _dummy(*args, **kwargs):
     func.__signature__ = (
         fsig.replace(parameters=tuple(dsig.parameters.values())))
 
-    # Concatenate docstrings
+    # Concatenate docstrings and copy summary
     # Make sure different sections are very visible
     doc = f"""
 ==========================={"="*len(name)}

diff --git a/proplot/wrappers.py b/proplot/wrappers.py
@@ -2717,6 +2717,7 @@ def _redirect(func):
     name = func.__name__
     @functools.wraps(func)
     def _wrapper(self, *args, **kwargs):
+        """"""
         if getattr(self, 'name', '') == 'basemap':
             return getattr(self.projection, name)(*args, ax=self, **kwargs)
         else:
@@ -2732,6 +2733,7 @@ def _norecurse(func):
     func._has_recurred = False
     @functools.wraps(func)
     def _wrapper(self, *args, **kwargs):
+        """"""
         if func._has_recurred:
             # Return the *original* version of the matplotlib method
             func._has_recurred = False
@@ -2754,6 +2756,7 @@ def _wrapper_decorator(driver):
     driver._docstring_orig = driver.__doc__ or ''
     driver._methods_wrapped = []
     def decorator(func):
+        """"""
         # Define wrapper
         @functools.wraps(func)
         def _wrapper(self, *args, **kwargs):