From afd3afb7682dd76a3f7e10dab907f884f92ff450 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Thu, 30 Jul 2015 11:08:57 -0400
Subject: [PATCH 01/13] Build API documentation for
 mpl_toolkit.axes_grid1.inset_locator

---
 doc/mpl_toolkits/axes_grid/api/index.rst             | 12 ++++++++++++
 doc/mpl_toolkits/axes_grid/api/inset_locator_api.rst |  7 +++++++
 2 files changed, 19 insertions(+)
 create mode 100644 doc/mpl_toolkits/axes_grid/api/inset_locator_api.rst

diff --git a/doc/mpl_toolkits/axes_grid/api/index.rst b/doc/mpl_toolkits/axes_grid/api/index.rst
index 399548928147..0e5975592c4b 100644
--- a/doc/mpl_toolkits/axes_grid/api/index.rst
+++ b/doc/mpl_toolkits/axes_grid/api/index.rst
@@ -13,3 +13,15 @@
     axes_divider_api.rst
     axes_grid_api.rst
     axis_artist_api.rst
+
+
+#######################################
+  The Matplotlib axes_grid1 Toolkit API
+#######################################
+
+:Release: |version|
+:Date: |today|
+
+.. toctree::
+
+    inset_locator_api.rst
diff --git a/doc/mpl_toolkits/axes_grid/api/inset_locator_api.rst b/doc/mpl_toolkits/axes_grid/api/inset_locator_api.rst
new file mode 100644
index 000000000000..c9c1bfbbb49c
--- /dev/null
+++ b/doc/mpl_toolkits/axes_grid/api/inset_locator_api.rst
@@ -0,0 +1,7 @@
+:mod:`mpl_toolkits.axes_grid1.inset_locator`
+============================================
+
+.. automodule:: mpl_toolkits.axes_grid1.inset_locator
+   :members:
+   :undoc-members:
+   :show-inheritance:

From 6bc091ce6af72589edf02884fc59137b418d4898 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Thu, 30 Jul 2015 11:09:46 -0400
Subject: [PATCH 02/13] Add documention for inset_locator.mark_inset in
 axes_grid1

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 36 +++++++++++++++++---
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index d8def8abd8be..2ee94f67fcd9 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -1,20 +1,17 @@
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
 
-from matplotlib.externals import six
 
 from matplotlib.offsetbox import AnchoredOffsetbox
- #from matplotlib.transforms import IdentityTransform
 
 import matplotlib.transforms as mtrans
 from .parasite_axes import HostAxes  # subclasses mpl_axes
 
 from matplotlib.transforms import Bbox, TransformedBbox, IdentityTransform
-
 from matplotlib.patches import Patch
 from matplotlib.path import Path
-
 from matplotlib.patches import Rectangle
+from matplotlib import docstring
 
 
 class InsetPosition(object):
@@ -311,7 +308,38 @@ def zoomed_inset_axes(parent_axes, zoom, loc=1,
     return inset_axes
 
 
+@docstring.dedent_interpd
 def mark_inset(parent_axes, inset_axes, loc1, loc2, **kwargs):
+    """
+    Draw a box to mark the location of an area represented by an inset axes.
+
+    This function draws a box in *parent_axes* at the bounding box of
+    *inset_axes*, and shows a connection with the inset axes by drawing lines
+    at the corners, giving a "zoomed in" effect.
+
+    Parameters
+    ----------
+    parent_axes : `matplotlib.axes.Axes`
+        Axes which contains the area of the inset axes.
+
+    inset_axes : `matplotlib.axes.Axes`
+        The inset axes.
+
+    loc1, loc2 : {1, 2, 3, 4}
+        Corners to use for connecting the inset axes and the area in the
+        parent axes.
+
+    The kwargs are Patch properties for the lines and box drawn:
+    %(Patch)s
+
+    Returns
+    -------
+    pp : `matplotlib.patches.Patch`
+        The patch drawn to represent the area of the inset axes.
+
+    p1, p2 : `matplotlib.patches.Patch`
+        The patches connecting two corners of the inset axes and its area.
+    """
     rect = TransformedBbox(inset_axes.viewLim, parent_axes.transData)
 
     pp = BboxPatch(rect, **kwargs)

From 281be9306340a6cfebc86ec3ac1821a59119379f Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Thu, 30 Jul 2015 21:11:42 -0400
Subject: [PATCH 03/13] Add documention to
 axis_grid1.inset_locator.zoomed_insert-axes

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 64 ++++++++++++++++++--
 1 file changed, 58 insertions(+), 6 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index 2ee94f67fcd9..d7b278ca24c5 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -282,11 +282,63 @@ def inset_axes(parent_axes, width, height, loc=1,
     return inset_axes
 
 
+@docstring.dedent_interpd
 def zoomed_inset_axes(parent_axes, zoom, loc=1,
-                       bbox_to_anchor=None, bbox_transform=None,
-                       axes_class=None,
-                       axes_kwargs=None,
-                       **kwargs):
+                      bbox_to_anchor=None, bbox_transform=None,
+                      axes_class=None,
+                      axes_kwargs=None,
+                      borderpad=0.5):
+    """
+    Create an anchored inset axes by scaling a parent axes.
+
+    Parameters
+    ----------
+    parent_axes : `matplotlib.axes.Axes`
+        Axes to place the inset axes.
+
+    zoom : float
+        Scaling factor of the data axes. *zoom* > 1 will enlargen the
+        coordinates (i.e., "zoomed in"), while *zoom* < 1 will shrink the
+        coordinates (i.e., "zoomed out").
+
+    loc : int or string, optional, default to 1
+        Location to place the inset axes. The valid locations are::
+
+            'upper right'  : 1,
+            'upper left'   : 2,
+            'lower left'   : 3,
+            'lower right'  : 4,
+            'right'        : 5,
+            'center left'  : 6,
+            'center right' : 7,
+            'lower center' : 8,
+            'upper center' : 9,
+            'center'       : 10
+
+    bbox_to_anchor : tuple or `matplotlib.transforms.BboxBase`, optional
+        Bbox that the inset axes will be anchored. Can be a tuple of
+        [left, bottom, width, height], or a tuple of [left, bottom].
+
+    bbox_transform : `matplotlib.transforms.Transform`, optional
+        Transformation for the bbox. if None, `parent_axes.transAxes` is used.
+
+    axes_class : `matplotlib.axes.Axes` type, optional
+        If specified, the inset axes created with be created with this class's
+        constructor.
+
+    axes_kwargs : dict, optional
+        Keyworded arguments to pass to the constructor of the inset axes.
+        Valid arguments include:
+        %(Axes)s
+
+    borderpad : float, optional
+        Padding between inset axes and the bbox_to_anchor. Defaults to 0.5.
+
+    Returns
+    -------
+    inset_axes : `axes_class`
+        Inset axes object created.
+    """
 
     if axes_class is None:
         axes_class = HostAxes
@@ -295,12 +347,12 @@ def zoomed_inset_axes(parent_axes, zoom, loc=1,
         inset_axes = axes_class(parent_axes.figure, parent_axes.get_position())
     else:
         inset_axes = axes_class(parent_axes.figure, parent_axes.get_position(),
-                               **axes_kwargs)
+                                **axes_kwargs)
 
     axes_locator = AnchoredZoomLocator(parent_axes, zoom=zoom, loc=loc,
                                        bbox_to_anchor=bbox_to_anchor,
                                        bbox_transform=bbox_transform,
-                                       **kwargs)
+                                       borderpad=borderpad)
     inset_axes.set_axes_locator(axes_locator)
 
     _add_inset_axes(parent_axes, inset_axes)

From a8f5eb67050d2fa64ab01fda6573d739913ee29d Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Thu, 30 Jul 2015 21:44:11 -0400
Subject: [PATCH 04/13] Add documentation for
 axis_grid1.inset_locator.inset_axis

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 65 ++++++++++++++++++--
 1 file changed, 59 insertions(+), 6 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index d7b278ca24c5..1c990e838f2d 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -251,11 +251,64 @@ def _add_inset_axes(parent_axes, inset_axes):
     inset_axes.set_navigate(False)
 
 
+@docstring.dedent_interpd
 def inset_axes(parent_axes, width, height, loc=1,
-                bbox_to_anchor=None, bbox_transform=None,
-                axes_class=None,
-                axes_kwargs=None,
-                **kwargs):
+               bbox_to_anchor=None, bbox_transform=None,
+               axes_class=None,
+               axes_kwargs=None,
+               borderpad=0.5):
+    """
+    Create an inset axes with a given width and height.
+
+    Both sizes used can be specified either in inches or percentage of the
+    parent axes.
+
+    Parameters
+    ----------
+    parent_axes : `matplotlib.axes.Axes`
+        Axes to place the inset axes.
+
+    width, height : float or str
+        Size of the inset axes to create.
+
+    loc : int or string, optional, default to 1
+        Location to place the inset axes. The valid locations are::
+
+            'upper right'  : 1,
+            'upper left'   : 2,
+            'lower left'   : 3,
+            'lower right'  : 4,
+            'right'        : 5,
+            'center left'  : 6,
+            'center right' : 7,
+            'lower center' : 8,
+            'upper center' : 9,
+            'center'       : 10
+
+    bbox_to_anchor : tuple or `matplotlib.transforms.BboxBase`, optional
+        Bbox that the inset axes will be anchored. Can be a tuple of
+        [left, bottom, width, height], or a tuple of [left, bottom].
+
+    bbox_transform : `matplotlib.transforms.Transform`, optional
+        Transformation for the bbox. if None, `parent_axes.transAxes` is used.
+
+    axes_class : `matplotlib.axes.Axes` type, optional
+        If specified, the inset axes created with be created with this class's
+        constructor.
+
+    axes_kwargs : dict, optional
+        Keyworded arguments to pass to the constructor of the inset axes.
+        Valid arguments include:
+        %(Axes)s
+
+    borderpad : float, optional
+        Padding between inset axes and the bbox_to_anchor. Defaults to 0.5.
+
+    Returns
+    -------
+    inset_axes : `axes_class`
+        Inset axes object created.
+    """
 
     if axes_class is None:
         axes_class = HostAxes
@@ -264,7 +317,7 @@ def inset_axes(parent_axes, width, height, loc=1,
         inset_axes = axes_class(parent_axes.figure, parent_axes.get_position())
     else:
         inset_axes = axes_class(parent_axes.figure, parent_axes.get_position(),
-                               **axes_kwargs)
+                                **axes_kwargs)
 
     if bbox_to_anchor is None:
         bbox_to_anchor = parent_axes.bbox
@@ -273,7 +326,7 @@ def inset_axes(parent_axes, width, height, loc=1,
                                        width, height,
                                        loc=loc,
                                        bbox_transform=bbox_transform,
-                                       **kwargs)
+                                       borderpad=borderpad)
 
     inset_axes.set_axes_locator(axes_locator)
 

From 748fff836587a137b99d237b48cbbf26cb18c962 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Fri, 31 Jul 2015 15:35:58 -0400
Subject: [PATCH 05/13] Add documentation for
 axis_grid1.inset_locator.InsetPosition

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 34 ++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index 1c990e838f2d..ae13962fbf63 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -14,11 +14,41 @@
 from matplotlib import docstring
 
 
+@docstring.dedent_interpd
 class InsetPosition(object):
+    """
+    An object for positioning an inset axes.
+
+    This is created by specifying the normalized coordinates in the axes,
+    instead of the figure.
+
+    Parameters
+    ----------
+    parent : `matplotlib.axes.Axes`
+        Axes to use for normalizing coordinates.
+
+    lbwh : iterable of four floats
+        The left edge, bottom edge, width, and height of the inset axes, in
+        units of the normalized coordinate of the *parent* axes.
+
+    See Also
+    --------
+    :meth:`matplotlib.axes.Axes.set_axes_locator`
+
+    Examples
+    --------
+    The following bounds the inset axes to a box with 20%% of the parent
+    axes's height and 40%% of the width. The size of the axes specified
+    ([0, 0, 1, 1]) ensures that the axes completely fills the bounding box:
+
+    >>> parent_axes = plt.gca()
+    >>> ax_ins = plt.axes([0, 0, 1, 1])
+    >>> ip = InsetPosition(ax, [0.5, 0.1, 0.4, 0.2])
+    >>> ax_ins.set_axes_locator(ip)
+    """
     def __init__(self, parent, lbwh):
         self.parent = parent
-        self.lbwh = lbwh  # position of the inset axes in
-                          # the normalized coordinate of the parent axes
+        self.lbwh = lbwh
 
     def __call__(self, ax, renderer):
         bbox_parent = self.parent.get_position(original=False)

From 2086399e30cb64b9e6001143e2539f5c768e8987 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Fri, 31 Jul 2015 16:05:38 -0400
Subject: [PATCH 06/13] Fix up imports in axis_grid1.inset_locator

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 34 +++++++++-----------
 1 file changed, 15 insertions(+), 19 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index ae13962fbf63..98f2231a9662 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -1,17 +1,15 @@
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
 
-
+from matplotlib import docstring
 from matplotlib.offsetbox import AnchoredOffsetbox
-
-import matplotlib.transforms as mtrans
-from .parasite_axes import HostAxes  # subclasses mpl_axes
-
-from matplotlib.transforms import Bbox, TransformedBbox, IdentityTransform
-from matplotlib.patches import Patch
+from matplotlib.patches import Patch, Rectangle
 from matplotlib.path import Path
-from matplotlib.patches import Rectangle
-from matplotlib import docstring
+from matplotlib.transforms import Bbox, BboxTransformTo
+from matplotlib.transforms import IdentityTransform, TransformedBbox
+
+from . import axes_size as Size
+from .parasite_axes import HostAxes
 
 
 @docstring.dedent_interpd
@@ -52,9 +50,9 @@ def __init__(self, parent, lbwh):
 
     def __call__(self, ax, renderer):
         bbox_parent = self.parent.get_position(original=False)
-        trans = mtrans.BboxTransformTo(bbox_parent)
-        bbox_inset = mtrans.Bbox.from_bounds(*self.lbwh)
-        bb = mtrans.TransformedBbox(bbox_inset, trans)
+        trans = BboxTransformTo(bbox_parent)
+        bbox_inset = Bbox.from_bounds(*self.lbwh)
+        bb = TransformedBbox(bbox_inset, trans)
         return bb
 
 
@@ -79,16 +77,13 @@ def __call__(self, ax, renderer):
         width, height, xdescent, ydescent = self.get_extent(renderer)
 
         px, py = self.get_offset(width, height, 0, 0, renderer)
-        bbox_canvas = mtrans.Bbox.from_bounds(px, py, width, height)
+        bbox_canvas = Bbox.from_bounds(px, py, width, height)
         tr = ax.figure.transFigure.inverted()
-        bb = mtrans.TransformedBbox(bbox_canvas, tr)
+        bb = TransformedBbox(bbox_canvas, tr)
 
         return bb
 
 
-from . import axes_size as Size
-
-
 class AnchoredSizeLocator(AnchoredLocatorBase):
     def __init__(self, bbox_to_anchor, x_size, y_size, loc,
                  borderpad=0.5, bbox_transform=None):
@@ -144,8 +139,8 @@ def __init__(self, parent_axes, zoom, loc,
 
     def get_extent(self, renderer):
 
-        bb = mtrans.TransformedBbox(self.axes.viewLim,
-                                    self.parent_axes.transData)
+        bb = TransformedBbox(self.axes.viewLim,
+                             self.parent_axes.transData)
 
         x, y, w, h = bb.bounds
 
@@ -277,6 +272,7 @@ def get_path(self):
 
 
 def _add_inset_axes(parent_axes, inset_axes):
+    """Helper function to add an inset axes and disable navigation in it"""
     parent_axes.figure.add_axes(inset_axes)
     inset_axes.set_navigate(False)
 

From 4c7abe586bedb31d49d433c998edc8b38f08ca9d Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Mon, 3 Aug 2015 11:22:14 -0400
Subject: [PATCH 07/13] Simplify axes_grid1's AnchoredLocatorBase subclasses.

Moved __call__ functionality in subclasses to parent class
Slight PEP8 cleanup
---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 39 +++++++-------------
 1 file changed, 13 insertions(+), 26 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index 98f2231a9662..cc4a510ddff2 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -59,17 +59,16 @@ def __call__(self, ax, renderer):
 class AnchoredLocatorBase(AnchoredOffsetbox):
     def __init__(self, bbox_to_anchor, offsetbox, loc,
                  borderpad=0.5, bbox_transform=None):
-
-        super(AnchoredLocatorBase, self).__init__(loc,
-                                                  pad=0., child=None,
-                                                  borderpad=borderpad,
-                                                 bbox_to_anchor=bbox_to_anchor,
-                                                 bbox_transform=bbox_transform)
+        super(AnchoredLocatorBase, self).__init__(
+            loc, pad=0., child=None, borderpad=borderpad,
+            bbox_to_anchor=bbox_to_anchor, bbox_transform=bbox_transform
+        )
 
     def draw(self, renderer):
         raise RuntimeError("No draw method should be called")
 
     def __call__(self, ax, renderer):
+        self.axes = ax
 
         fontsize = renderer.points_to_pixels(self.prop.get_size_in_points())
         self._update_offset_func(renderer, fontsize)
@@ -88,15 +87,15 @@ class AnchoredSizeLocator(AnchoredLocatorBase):
     def __init__(self, bbox_to_anchor, x_size, y_size, loc,
                  borderpad=0.5, bbox_transform=None):
 
-        super(AnchoredSizeLocator, self).__init__(bbox_to_anchor, None, loc,
-                                                 borderpad=borderpad,
-                                                 bbox_transform=bbox_transform)
+        super(AnchoredSizeLocator, self).__init__(
+            bbox_to_anchor, None, loc,
+            borderpad=borderpad, bbox_transform=bbox_transform
+        )
 
         self.x_size = Size.from_any(x_size)
         self.y_size = Size.from_any(y_size)
 
     def get_extent(self, renderer):
-
         x, y, w, h = self.get_bbox_to_anchor().bounds
 
         dpi = renderer.points_to_pixels(72.)
@@ -113,15 +112,10 @@ def get_extent(self, renderer):
 
         return width+2*pad, height+2*pad, xd+pad, yd+pad
 
-    def __call__(self, ax, renderer):
-
-        self.axes = ax
-        return super(AnchoredSizeLocator, self).__call__(ax, renderer)
-
 
 class AnchoredZoomLocator(AnchoredLocatorBase):
     def __init__(self, parent_axes, zoom, loc,
-                  borderpad=0.5,
+                 borderpad=0.5,
                  bbox_to_anchor=None,
                  bbox_transform=None):
 
@@ -131,14 +125,11 @@ def __init__(self, parent_axes, zoom, loc,
         if bbox_to_anchor is None:
             bbox_to_anchor = parent_axes.bbox
 
-        super(AnchoredZoomLocator, self).__init__(bbox_to_anchor, None, loc,
-                                                 borderpad=borderpad,
-                                                 bbox_transform=bbox_transform)
-
-        self.axes = None
+        super(AnchoredZoomLocator, self).__init__(
+            bbox_to_anchor, None, loc, borderpad=borderpad,
+            bbox_transform=bbox_transform)
 
     def get_extent(self, renderer):
-
         bb = TransformedBbox(self.axes.viewLim,
                              self.parent_axes.transData)
 
@@ -151,10 +142,6 @@ def get_extent(self, renderer):
 
         return w*self.zoom+2*pad, h*self.zoom+2*pad, xd+pad, yd+pad
 
-    def __call__(self, ax, renderer):
-        self.axes = ax
-        return super(AnchoredZoomLocator, self).__call__(ax, renderer)
-
 
 class BboxPatch(Patch):
     def __init__(self, bbox, **kwargs):

From b857f7115823d6bbccf6e2a96f5f9c9d80ba6516 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Mon, 3 Aug 2015 22:42:16 -0400
Subject: [PATCH 08/13] Add docstring for axes_grid1.inset_locator.BboxPatch

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index cc4a510ddff2..564f4191c734 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -143,7 +143,19 @@ def get_extent(self, renderer):
         return w*self.zoom+2*pad, h*self.zoom+2*pad, xd+pad, yd+pad
 
 
+@docstring.dedent_interpd
 class BboxPatch(Patch):
+    """
+    Patch showing the shape bounded by a Bbox.
+
+    Parameters
+    ----------
+    bbox : `matplotlib.transforms.Bbox`
+        Bbox to use for the extents of this patch.
+
+    The kwargs are Patch properties:
+    %(Patch)s
+    """
     def __init__(self, bbox, **kwargs):
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
@@ -170,6 +182,7 @@ def get_path(self):
                  Path.CLOSEPOLY]
 
         return Path(verts, codes)
+    get_path.__doc__ = Patch.get_path.__doc__
 
 
 class BboxConnector(Patch):

From 9c0cff1dae06c6c66e25ec3ff692a4bc2fbe4361 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Tue, 4 Aug 2015 14:56:30 -0400
Subject: [PATCH 09/13] Add documentation for
 axes_grid1.inset_locator.BboxConnector

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 95 +++++++++++++++++---
 1 file changed, 81 insertions(+), 14 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index 564f4191c734..3c8200a26db5 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -185,10 +185,59 @@ def get_path(self):
     get_path.__doc__ = Patch.get_path.__doc__
 
 
+@docstring.dedent_interpd
 class BboxConnector(Patch):
+    """
+    Connect two bboxes with a straight line.
+
+    Parameters
+    ----------
+    bbox1, bbox2 : `matplotlib.transforms.Bbox`
+        Bounding boxes to connect.
+
+    loc1 : {1, 2, 3, 4}
+        Corner of *bbox1* to draw the line. Valid values are::
+
+            'upper right'  : 1,
+            'upper left'   : 2,
+            'lower left'   : 3,
+            'lower right'  : 4
+
+    loc2 : {1, 2, 3, 4}, optional
+        Corner of *bbox2* to draw the line. If None, defaults to *loc1*.
+        Valid values are::
+
+            'upper right'  : 1,
+            'upper left'   : 2,
+            'lower left'   : 3,
+            'lower right'  : 4
+
+    The kwargs are Patch properties for the line drawn:
+    %(Patch)s
+    """
 
     @staticmethod
     def get_bbox_edge_pos(bbox, loc):
+        """
+        Helper function to obtain the location of a corner of a bbox
+
+        Parameters
+        ----------
+        bbox : `matplotlib.transforms.Bbox`
+
+        loc : {1, 2, 3, 4}
+            Corner of *bbox*. Valid values are::
+
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
+
+        Returns
+        -------
+        x, y : float
+            Coordinates of the corner specified by *loc*.
+        """
         x0, y0, x1, y1 = bbox.extents
         if loc == 1:
             return x1, y1
@@ -201,6 +250,37 @@ def get_bbox_edge_pos(bbox, loc):
 
     @staticmethod
     def connect_bbox(bbox1, bbox2, loc1, loc2=None):
+        """
+        Helper function to obtain a Path from one bbox to another.
+
+        Parameters
+        ----------
+        bbox1, bbox2 : `matplotlib.transforms.Bbox`
+            Bounding boxes to connect.
+
+        loc1 : {1, 2, 3, 4}
+            Corner of *bbox1* to use. Valid values are::
+
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
+
+        loc2 : {1, 2, 3, 4}, optional
+            Corner of *bbox2* to use. If None, defaults to *loc1*.
+            Valid values are::
+
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
+
+        Returns
+        -------
+        path : `matplotlib.path.Path`
+            A line segment from the *loc1* corner of *bbox1* to the *loc2*
+            corner of *bbox2*.
+        """
         if isinstance(bbox1, Rectangle):
             transform = bbox1.get_transfrom()
             bbox1 = Bbox.from_bounds(0, 0, 1, 1)
@@ -218,25 +298,11 @@ def connect_bbox(bbox1, bbox2, loc1, loc2=None):
         x2, y2 = BboxConnector.get_bbox_edge_pos(bbox2, loc2)
 
         verts = [[x1, y1], [x2, y2]]
-        #Path()
-
         codes = [Path.MOVETO, Path.LINETO]
 
         return Path(verts, codes)
 
     def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs):
-        """
-        *path* is a :class:`matplotlib.path.Path` object.
-
-        Valid kwargs are:
-        %(Patch)s
-
-        .. seealso::
-
-            :class:`Patch`
-                For additional kwargs
-
-        """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
 
@@ -250,6 +316,7 @@ def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs):
     def get_path(self):
         return self.connect_bbox(self.bbox1, self.bbox2,
                                  self.loc1, self.loc2)
+    get_path.__doc__ = Patch.get_path.__doc__
 
 
 class BboxConnectorPatch(BboxConnector):

From 089805223736d9d36358742e70dee606a6597100 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Tue, 4 Aug 2015 15:28:01 -0400
Subject: [PATCH 10/13] Add documentation for
 axes_grid1.inset_locator.BboxConnectorPatch

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 35 ++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index 3c8200a26db5..d13d9f982628 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -319,8 +319,42 @@ def get_path(self):
     get_path.__doc__ = Patch.get_path.__doc__
 
 
+@docstring.dedent_interpd
 class BboxConnectorPatch(BboxConnector):
+    """
+    Connect two bboxes with a quadrilateral.
 
+    The quadrilateral is specified by two lines that start and end at corners
+    of the bboxes. The four sides of the quadrilateral are defined by the two
+    lines given, the line between the two corners specified in *bbox1* and the
+    line between the two corners specified in *bbox2*.
+
+    Parameters
+    ----------
+    bbox1, bbox2 : `matplotlib.transforms.Bbox`
+        Bounding boxes to connect.
+
+    loc1a, loc2a : {1, 2, 3, 4}
+        Corners of *bbox1* and *bbox2* to draw the first line.
+        Valid values are::
+
+            'upper right'  : 1,
+            'upper left'   : 2,
+            'lower left'   : 3,
+            'lower right'  : 4
+
+    loc1b, loc2b : {1, 2, 3, 4}
+        Corners of *bbox1* and *bbox2* to draw the second line.
+        Valid values are::
+
+            'upper right'  : 1,
+            'upper left'   : 2,
+            'lower left'   : 3,
+            'lower right'  : 4
+
+    The kwargs are Patch properties for the line drawn:
+    %(Patch)s
+    """
     def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs):
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
@@ -336,6 +370,7 @@ def get_path(self):
                        list(path2.vertices) +
                        [path1.vertices[0]])
         return Path(path_merged)
+    get_path.__doc__ = BboxConnector.get_path.__doc__
 
 
 def _add_inset_axes(parent_axes, inset_axes):

From e49942551edffcbd5a8af622171c11c034da3fb0 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Tue, 4 Aug 2015 15:40:15 -0400
Subject: [PATCH 11/13] Add module doc for axes_grid1.inset_locator

---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index d13d9f982628..df2a09dd1c6e 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -1,3 +1,6 @@
+"""
+A collection of functions and objects for creating or placing inset axes.
+"""
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
 

From a55250f42f5fc01ff1de20d8fa6eec49caaa9179 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Tue, 4 Aug 2015 20:59:23 -0400
Subject: [PATCH 12/13] Move class docstrings in axes_grid1.inset_locator to
 constructors

Fixes Py2k compatibility
---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 199 +++++++++----------
 1 file changed, 99 insertions(+), 100 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index df2a09dd1c6e..3539e03331c0 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -15,39 +15,39 @@
 from .parasite_axes import HostAxes
 
 
-@docstring.dedent_interpd
 class InsetPosition(object):
-    """
-    An object for positioning an inset axes.
+    @docstring.dedent_interpd
+    def __init__(self, parent, lbwh):
+        """
+        An object for positioning an inset axes.
 
-    This is created by specifying the normalized coordinates in the axes,
-    instead of the figure.
+        This is created by specifying the normalized coordinates in the axes,
+        instead of the figure.
 
-    Parameters
-    ----------
-    parent : `matplotlib.axes.Axes`
-        Axes to use for normalizing coordinates.
-
-    lbwh : iterable of four floats
-        The left edge, bottom edge, width, and height of the inset axes, in
-        units of the normalized coordinate of the *parent* axes.
-
-    See Also
-    --------
-    :meth:`matplotlib.axes.Axes.set_axes_locator`
-
-    Examples
-    --------
-    The following bounds the inset axes to a box with 20%% of the parent
-    axes's height and 40%% of the width. The size of the axes specified
-    ([0, 0, 1, 1]) ensures that the axes completely fills the bounding box:
-
-    >>> parent_axes = plt.gca()
-    >>> ax_ins = plt.axes([0, 0, 1, 1])
-    >>> ip = InsetPosition(ax, [0.5, 0.1, 0.4, 0.2])
-    >>> ax_ins.set_axes_locator(ip)
-    """
-    def __init__(self, parent, lbwh):
+        Parameters
+        ----------
+        parent : `matplotlib.axes.Axes`
+            Axes to use for normalizing coordinates.
+
+        lbwh : iterable of four floats
+            The left edge, bottom edge, width, and height of the inset axes, in
+            units of the normalized coordinate of the *parent* axes.
+
+        See Also
+        --------
+        :meth:`matplotlib.axes.Axes.set_axes_locator`
+
+        Examples
+        --------
+        The following bounds the inset axes to a box with 20%% of the parent
+        axes's height and 40%% of the width. The size of the axes specified
+        ([0, 0, 1, 1]) ensures that the axes completely fills the bounding box:
+
+        >>> parent_axes = plt.gca()
+        >>> ax_ins = plt.axes([0, 0, 1, 1])
+        >>> ip = InsetPosition(ax, [0.5, 0.1, 0.4, 0.2])
+        >>> ax_ins.set_axes_locator(ip)
+        """
         self.parent = parent
         self.lbwh = lbwh
 
@@ -146,20 +146,20 @@ def get_extent(self, renderer):
         return w*self.zoom+2*pad, h*self.zoom+2*pad, xd+pad, yd+pad
 
 
-@docstring.dedent_interpd
 class BboxPatch(Patch):
-    """
-    Patch showing the shape bounded by a Bbox.
+    @docstring.dedent_interpd
+    def __init__(self, bbox, **kwargs):
+        """
+        Patch showing the shape bounded by a Bbox.
 
-    Parameters
-    ----------
-    bbox : `matplotlib.transforms.Bbox`
-        Bbox to use for the extents of this patch.
+        Parameters
+        ----------
+        bbox : `matplotlib.transforms.Bbox`
+            Bbox to use for the extents of this patch.
 
-    The kwargs are Patch properties:
-    %(Patch)s
-    """
-    def __init__(self, bbox, **kwargs):
+        The kwargs are Patch properties:
+        %(Patch)s
+        """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
 
@@ -188,37 +188,7 @@ def get_path(self):
     get_path.__doc__ = Patch.get_path.__doc__
 
 
-@docstring.dedent_interpd
 class BboxConnector(Patch):
-    """
-    Connect two bboxes with a straight line.
-
-    Parameters
-    ----------
-    bbox1, bbox2 : `matplotlib.transforms.Bbox`
-        Bounding boxes to connect.
-
-    loc1 : {1, 2, 3, 4}
-        Corner of *bbox1* to draw the line. Valid values are::
-
-            'upper right'  : 1,
-            'upper left'   : 2,
-            'lower left'   : 3,
-            'lower right'  : 4
-
-    loc2 : {1, 2, 3, 4}, optional
-        Corner of *bbox2* to draw the line. If None, defaults to *loc1*.
-        Valid values are::
-
-            'upper right'  : 1,
-            'upper left'   : 2,
-            'lower left'   : 3,
-            'lower right'  : 4
-
-    The kwargs are Patch properties for the line drawn:
-    %(Patch)s
-    """
-
     @staticmethod
     def get_bbox_edge_pos(bbox, loc):
         """
@@ -305,7 +275,36 @@ def connect_bbox(bbox1, bbox2, loc1, loc2=None):
 
         return Path(verts, codes)
 
+    @docstring.dedent_interpd
     def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs):
+        """
+        Connect two bboxes with a straight line.
+
+        Parameters
+        ----------
+        bbox1, bbox2 : `matplotlib.transforms.Bbox`
+            Bounding boxes to connect.
+
+        loc1 : {1, 2, 3, 4}
+            Corner of *bbox1* to draw the line. Valid values are::
+
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
+
+        loc2 : {1, 2, 3, 4}, optional
+            Corner of *bbox2* to draw the line. If None, defaults to *loc1*.
+            Valid values are::
+
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
+
+        The kwargs are Patch properties for the line drawn:
+        %(Patch)s
+        """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
 
@@ -322,43 +321,43 @@ def get_path(self):
     get_path.__doc__ = Patch.get_path.__doc__
 
 
-@docstring.dedent_interpd
 class BboxConnectorPatch(BboxConnector):
-    """
-    Connect two bboxes with a quadrilateral.
+    @docstring.dedent_interpd
+    def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs):
+        """
+        Connect two bboxes with a quadrilateral.
 
-    The quadrilateral is specified by two lines that start and end at corners
-    of the bboxes. The four sides of the quadrilateral are defined by the two
-    lines given, the line between the two corners specified in *bbox1* and the
-    line between the two corners specified in *bbox2*.
+        The quadrilateral is specified by two lines that start and end at corners
+        of the bboxes. The four sides of the quadrilateral are defined by the two
+        lines given, the line between the two corners specified in *bbox1* and the
+        line between the two corners specified in *bbox2*.
 
-    Parameters
-    ----------
-    bbox1, bbox2 : `matplotlib.transforms.Bbox`
-        Bounding boxes to connect.
+        Parameters
+        ----------
+        bbox1, bbox2 : `matplotlib.transforms.Bbox`
+            Bounding boxes to connect.
 
-    loc1a, loc2a : {1, 2, 3, 4}
-        Corners of *bbox1* and *bbox2* to draw the first line.
-        Valid values are::
+        loc1a, loc2a : {1, 2, 3, 4}
+            Corners of *bbox1* and *bbox2* to draw the first line.
+            Valid values are::
 
-            'upper right'  : 1,
-            'upper left'   : 2,
-            'lower left'   : 3,
-            'lower right'  : 4
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
 
-    loc1b, loc2b : {1, 2, 3, 4}
-        Corners of *bbox1* and *bbox2* to draw the second line.
-        Valid values are::
+        loc1b, loc2b : {1, 2, 3, 4}
+            Corners of *bbox1* and *bbox2* to draw the second line.
+            Valid values are::
 
-            'upper right'  : 1,
-            'upper left'   : 2,
-            'lower left'   : 3,
-            'lower right'  : 4
+                'upper right'  : 1,
+                'upper left'   : 2,
+                'lower left'   : 3,
+                'lower right'  : 4
 
-    The kwargs are Patch properties for the line drawn:
-    %(Patch)s
-    """
-    def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs):
+        The kwargs are Patch properties for the line drawn:
+        %(Patch)s
+        """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
         BboxConnector.__init__(self, bbox1, bbox2, loc1a, loc2a, **kwargs)

From e6181ded90fefc3f01d723df4bfdb64eb1cdfbd8 Mon Sep 17 00:00:00 2001
From: Joseph Jon Booker <joe@neoturbine.net>
Date: Wed, 18 Nov 2015 15:01:49 -0500
Subject: [PATCH 13/13] Reform kwarg documentation in axes_grid1.inset_locator

Add six import for consistency
---
 lib/mpl_toolkits/axes_grid1/inset_locator.py | 21 ++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/lib/mpl_toolkits/axes_grid1/inset_locator.py b/lib/mpl_toolkits/axes_grid1/inset_locator.py
index 3539e03331c0..43ed8dca6844 100644
--- a/lib/mpl_toolkits/axes_grid1/inset_locator.py
+++ b/lib/mpl_toolkits/axes_grid1/inset_locator.py
@@ -5,6 +5,7 @@
                         unicode_literals)
 
 from matplotlib import docstring
+from matplotlib.externals import six
 from matplotlib.offsetbox import AnchoredOffsetbox
 from matplotlib.patches import Patch, Rectangle
 from matplotlib.path import Path
@@ -157,8 +158,9 @@ def __init__(self, bbox, **kwargs):
         bbox : `matplotlib.transforms.Bbox`
             Bbox to use for the extents of this patch.
 
-        The kwargs are Patch properties:
-        %(Patch)s
+        **kwargs
+            Patch properties. Valid arguments include:
+            %(Patch)s
         """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
@@ -302,8 +304,9 @@ def __init__(self, bbox1, bbox2, loc1, loc2=None, **kwargs):
                 'lower left'   : 3,
                 'lower right'  : 4
 
-        The kwargs are Patch properties for the line drawn:
-        %(Patch)s
+        **kwargs
+            Patch properties for the line drawn. Valid arguments include:
+            %(Patch)s
         """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
@@ -355,8 +358,9 @@ def __init__(self, bbox1, bbox2, loc1a, loc2a, loc1b, loc2b, **kwargs):
                 'lower left'   : 3,
                 'lower right'  : 4
 
-        The kwargs are Patch properties for the line drawn:
-        %(Patch)s
+        **kwargs
+            Patch properties for the line drawn:
+            %(Patch)s
         """
         if "transform" in kwargs:
             raise ValueError("transform should not be set")
@@ -564,8 +568,9 @@ def mark_inset(parent_axes, inset_axes, loc1, loc2, **kwargs):
         Corners to use for connecting the inset axes and the area in the
         parent axes.
 
-    The kwargs are Patch properties for the lines and box drawn:
-    %(Patch)s
+    **kwargs
+        Patch properties for the lines and box drawn:
+        %(Patch)s
 
     Returns
     -------