Add _concatenate_axes_docstrings, make behavior dependent on whether …

…running sphinx Minor
proplot-dev · lukelbd · Sep 17, 2019 · Sep 17, 2019 · Sep 17, 2019 · Sep 17, 2019
commit a89016c193e6497cb63392f616857c843c7e2b3e
diff --git a/docs/conf.py b/docs/conf.py
@@ -13,6 +13,7 @@
 
 import os
 import sys
+import matplotlib # loads local matplotlibrc which sets up docstring settings
 
 # Sphinx-automodapi requires proplot on path
 sys.path.insert(0, os.path.abspath('..'))

diff --git a/docs/matplotlibrc b/docs/matplotlibrc
@@ -0,0 +1,3 @@
+backend            : Agg
+savefig.dpi        : 80   # figure dots per inch
+docstring.hardcopy : True # set this when you want to generate hardcopy docstring
diff --git a/proplot/axes.py b/proplot/axes.py
@@ -17,6 +17,7 @@
 """
 import re
 import numpy as np
+import inspect
 import warnings
 import functools
 from matplotlib import docstring
@@ -92,6 +93,57 @@
     'lc':    'lower center',
     }
 
+# Concatenates docstrings and obfuscates call signature
+# NOTE: Originally had idea to use numpydoc.docscrape.NumpyDocString to
+# interpolate docstrings but *enormous* number of assupmtions would go into
+# this. And simple is better than complex.
+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
+        return func
+
+    # Obfuscate signature by converting to *args **kwargs. Note this does
+    # not change behavior of function! Copy parameters from a dummy function
+    # because I'm too lazy to figure out inspect.Parameters API
+    # See: https://stackoverflow.com/a/33112180/4970632
+    def _dummy(*args, **kwargs):
+        pass
+    dsig = inspect.signature(_dummy)
+    fsig = inspect.signature(func)
+    func.__signature__ = (
+        fsig.replace(parameters=tuple(dsig.parameters.values())))
+
+    # Concatenate docstrings
+    # Make sure different sections are very visible
+    doc = f"""
+==========================={"="*len(name)}
+proplot.Axes.{name} documentation
+==========================={"="*len(name)}
+{fdoc}
+
+==================================={"="*len(name)}
+matplotlib.axes.Axes.{name} documentation
+==================================={"="*len(name)}
+{odoc}
+"""
+    func.__doc__ = doc
+
+    # Return
+    return func
+
 # Helper function
 ABC_STRING = 'abcdefghijklmnopqrstuvwxyz'
 def _abc(i):

diff --git a/proplot/subplots.py b/proplot/subplots.py
@@ -78,6 +78,7 @@
     import matplotlib.backends.backend_macosx as mbackend
 except ImportError:
     mbackend = None
+from matplotlib import docstring
 from .rctools import rc
 from .utils import _notNone, _counter, units
 from . import projs, axes
@@ -109,6 +110,28 @@
     'aaas1': '5.5cm', # AAAS (e.g., Science) 1 column
     'aaas2': '12cm', # AAAS 2 column
     }
+# Table that goes in the subplots docstring
+# Must be indented one space as this is embedded in parameter description
+journal_doc = """
+    ===========  ====================  ==========================================================================================================================================================
+    Key          Size description      Organization
+    ===========  ====================  ==========================================================================================================================================================
+    ``'pnas1'``  1-column              `Proceedings of the National Academy of Sciences <http://www.pnas.org/page/authors/submission>`__
+    ``'pnas2'``  2-column              ”
+    ``'pnas3'``  landscape page        ”
+    ``'ams1'``   1-column              `American Meteorological Society <https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/>`__
+    ``'ams2'``   small 2-column        ”
+    ``'ams3'``   medium 2-column       ”
+    ``'ams4'``   full 2-column         ”
+    ``'agu1'``   1-column              `American Geophysical Union <https://publications.agu.org/author-resource-center/figures-faq/>`__
+    ``'agu2'``   2-column              ”
+    ``'agu3'``   full height 1-column  ”
+    ``'agu4'``   full height 2-column  ”
+    ``'aaas1'``  1-column              `American Association for the Advancement of Science <https://www.sciencemag.org/authors/instructions-preparing-initial-manuscript>`__
+    ``'aaas2'``  2-column              ”
+    ===========  ====================  ==========================================================================================================================================================
+"""
+docstring.interpd.update(journal_doc=journal_doc)
 
 
 #-----------------------------------------------------------------------------#
@@ -1721,6 +1744,7 @@ def _axes_dict(naxs, value, kw=False, default=None):
         raise ValueError(f'Have {naxs} axes, but {value} has properties for axes {", ".join(str(i) for i in sorted(kwargs.keys()))}.')
     return kwargs
 
+@docstring.dedent_interpd
 def subplots(array=None, ncols=1, nrows=1,
     ref=1, order='C',
     aspect=1, figsize=None,
@@ -1738,19 +1762,15 @@ def subplots(array=None, ncols=1, nrows=1,
     autoformat=True, includepanels=False,
     ):
     """
-    Analogous to `matplotlib.pyplot.subplots`, creates a figure with a single
-    axes or arbitrary grids of axes, any of which can be map projections,
-    and optional "panels" along axes or figure edges.
-
-    The parameters are sorted into the following rough sections: subplot grid
-    specifications, figure and subplot sizes, axis sharing,
-    figure panels, axes panels, and map projections.
+    Analogous to `matplotlib.pyplot.subplots`. Creates a figure with an
+    arbitrary layout of axes belong to arbitrary projections, and accepts
+    various `Figure` and `FlexibleGridSpec` parameters.
 
     Parameters
     ----------
     ncols, nrows : int, optional
-        Number of columns, rows. Ignored if `array` is not ``None``.
-        Use these arguments for simpler subplot grids.
+        Number of columns, rows in the subplot layout. Ignored if `array` is
+        passed. Default is ``1``.
     order : {'C', 'F'}, optional
         Whether subplots are numbered in column-major (``'C'``) or row-major
         (``'F'``) order. Analogous to `numpy.array` ordering. This controls
@@ -1774,8 +1794,8 @@ def subplots(array=None, ncols=1, nrows=1,
     journal : str, optional
         String name corresponding to an academic journal standard that is used
         to control the figure width (and height, if specified). Valid names
-        are described in a table below.
-
+        are as follows.
+        %(journal_doc)s
     ref : int, optional
         The reference axes number. The `axwidth`, `axheight`, and `aspect`
         keyword args are applied to this axes, and aspect ratio is conserved
@@ -1901,26 +1921,6 @@ def subplots(array=None, ncols=1, nrows=1,
         The figure instance.
     axs : `axes_grid`
         A special list of axes instances. See `axes_grid`.
-
-
-    Current options for the `journal` keyword argument are as follows.
-    If you'd like to add additional standards, feel free to submit a pull request
-
-    ===========  ====================  ==========================================================================================================================================================
-    Key          Size description      Organization
-    ===========  ====================  ==========================================================================================================================================================
-    ``'pnas1'``  1-column              `Proceedings of the National Academy of Sciences <http://www.pnas.org/page/authors/submission>`__
-    ``'pnas2'``  2-column              ”
-    ``'pnas3'``  landscape page        ”
-    ``'ams1'``   1-column              `American Meteorological Society <https://www.ametsoc.org/ams/index.cfm/publications/authors/journal-and-bams-authors/figure-information-for-authors/>`__
-    ``'ams2'``   small 2-column        ”
-    ``'ams3'``   medium 2-column       ”
-    ``'ams4'``   full 2-column         ”
-    ``'agu1'``   1-column              `American Geophysical Union <https://publications.agu.org/author-resource-center/figures-faq/>`__
-    ``'agu2'``   2-column              ”
-    ``'agu3'``   full height 1-column  ”
-    ``'agu4'``   full height 2-column  ”
-    ===========  ====================  ==========================================================================================================================================================
     """
     rc._getitem_mode = 0 # ensure still zero; might be non-zero if had error in 'with context' block
     # Build array

diff --git a/proplot/wrappers.py b/proplot/wrappers.py
@@ -7,6 +7,7 @@
 import numpy.ma as ma
 import functools
 import warnings
+from matplotlib import docstring
 from . import utils, styletools, axistools
 from .utils import _notNone
 import matplotlib.axes as maxes

diff --git a/setup.py b/setup.py
@@ -7,21 +7,25 @@
 #   https://stackoverflow.com/a/1857436/4970632
 from setuptools import setup
 setup(
-    name = 'proplot',
-    url = 'https://lukelbd.github.io/proplot',
-    author = 'Luke Davis',
-    version = '1.0',
-    author_email = '[email protected]',
-    python_requires = '>=3.6.0',
-    project_urls={
+    name             = 'proplot',
+    url              = 'https://lukelbd.github.io/proplot',
+    author           = 'Luke Davis',
+    version          = '1.0',
+    author_email     = '[email protected]',
+    python_requires  = '>=3.6.0',
+    project_urls     = {
         'Bug Tracker': 'https://github.com/lukelbd/proplot/issues',
         'Documentation':  'https://lukelbd.github.io/proplot',
         'Source Code': 'https://github.com/lukelbd/proplot'
         },
-    packages = ['proplot'], # reserve name
-    package_data = {'': ['cmaps/*', 'fonts/*', 'colors/*', '.proplotrc']},
-    install_requires = ['matplotlib>=2.2', 'numpy>=1.11', 'lxml>=4.0.0'],
-    license = open('LICENSE.txt').read(),
-    description = 'Matplotlib wrapper for making beautiful, publication-quality graphics.',
+    packages         = ['proplot'], # reserve name
+    package_data     = {'': [
+        'cmaps/*', 'fonts/*', 'colors/*', '.proplotrc'
+        ]},
+    install_requires = [
+        'matplotlib>=2.2', 'numpy>=1.11', 'lxml>=4.0.0',
+        ],
+    license          = open('LICENSE.txt').read(),
+    description      = 'A comprehensive matplotlib wrapper for making beautiful, publication-quality graphics.',
     long_description = open('README.rst').read(),
 )