matplotlib · jklymak · May 11, 2020 · May 12, 2020 · May 12, 2020 · May 14, 2020
diff --git a/doc/api/figure_api.rst b/doc/api/figure_api.rst
@@ -15,8 +15,9 @@ Classes
    :toctree: _as_gen/
    :template: autosummary.rst
    :nosignatures:
+   :inhereted-members:
 
-   AxesStack
+   SubPanel
    Figure
    SubplotParams
 

diff --git a/doc/users/prev_whats_new/whats_new_3.0.rst b/doc/users/prev_whats_new/whats_new_3.0.rst
@@ -214,7 +214,7 @@ to a figure. E.g. ::
    fig.add_artist(circ)
 
 In case the added artist has no transform set previously, it will be set to
-the figure transform (``fig.transFigure``).
+the figure transform (``fig.transPanel``).
 This new method may be useful for adding artists to figures without axes or to
 easily position static elements in figure coordinates.
 

diff --git a/examples/axes_grid1/inset_locator_demo.py b/examples/axes_grid1/inset_locator_demo.py
@@ -136,7 +136,7 @@
 # Create an inset horizontally centered in figure coordinates and vertically
 # bound to line up with the axes.
 from matplotlib.transforms import blended_transform_factory
-transform = blended_transform_factory(fig.transFigure, ax2.transAxes)
+transform = blended_transform_factory(fig.transPanel, ax2.transAxes)
 axins4 = inset_axes(ax2, width="16%", height="34%",
                     bbox_to_anchor=(0, 0, 1, 1),
                     bbox_transform=transform, loc=8, borderpad=0)

diff --git a/examples/pyplots/auto_subplots_adjust.py b/examples/pyplots/auto_subplots_adjust.py
@@ -26,7 +26,7 @@ def on_draw(event):
         bbox = label.get_window_extent()
         # the figure transform goes from relative coords->pixels and we
         # want the inverse of that
-        bboxi = bbox.transformed(fig.transFigure.inverted())
+        bboxi = bbox.transformed(fig.transPanel.inverted())
         bboxes.append(bboxi)
     # the bbox that bounds all the bboxes, again in relative figure coords
     bbox = mtransforms.Bbox.union(bboxes)

diff --git a/examples/subplots_axes_and_figures/gridspec_nested.py b/examples/subplots_axes_and_figures/gridspec_nested.py
@@ -16,7 +16,6 @@ def format_axes(fig):
         ax.text(0.5, 0.5, "ax%d" % (i+1), va="center", ha="center")
         ax.tick_params(labelbottom=False, labelleft=False)
 
-
 # gridspec inside gridspec
 fig = plt.figure()
 

diff --git a/examples/subplots_axes_and_figures/subpanels.py b/examples/subplots_axes_and_figures/subpanels.py
@@ -0,0 +1,48 @@
+"""
+================
+Nested Subpanels
+================
+
+Sometimes it is desirable to have a figure that has two different
+layouts in it.  This can be achieved with
+:doc:`nested gridspecs</gallery/subplots_axes_and_figures/gridspec_nested>`
+but having a virtual figure with its own artists is helpful, so
+Matplotlib also has "subpanels", usually implimented by calling
+``.figure.PanelBase.add_subpanel`` in a way that is analagous to
+``.figure.PanelBase.add_subplot``.
+
+"""
+import matplotlib.pyplot as plt
+import numpy as np
+
+def example_plot(ax, fontsize=12, hide_labels=False):
+    ax.pcolormesh(np.random.randn(30, 30))
+    if not hide_labels:
+        ax.set_xlabel('x-label', fontsize=fontsize)
+        ax.set_ylabel('y-label', fontsize=fontsize)
+        ax.set_title('Title', fontsize=fontsize)
+
+
+# gridspec inside gridspec
+fig = plt.figure(constrained_layout=True)
+subpanels = fig.subpanels(1, 2, wspace=0.07)
+
+axsLeft = subpanels[0].subplots(1, 2, sharey=True)
+subpanels[0].set_facecolor('0.75')
+for ax in axsLeft:
+    example_plot(ax)
+subpanels[0].suptitle('Left plots', fontsize='x-large')
+
+axsRight = subpanels[1].subplots(3, 1, sharex=True)
+for nn, ax in enumerate(axsRight):
+    example_plot(ax, hide_labels=True)
+    if nn == 2:
+        ax.set_xlabel('xlabel')
+    if nn == 1:
+        ax.set_ylabel('ylabel')
+subpanels[1].suptitle('Right plots', fontsize='x-large')
+
+fig.suptitle('Figure suptitle', fontsize='xx-large')
+
+plt.show()
+
diff --git a/examples/subplots_axes_and_figures/subplots_demo.py b/examples/subplots_axes_and_figures/subplots_demo.py
@@ -144,7 +144,7 @@
 # Still there remains an unused empty space between the subplots.
 #
 # To precisely control the positioning of the subplots, one can explicitly
-# create a `.GridSpec` with `.add_gridspec`, and then call its
+# create a `.GridSpec` with `~.Figure.add_gridspec`, and then call its
 # `~.GridSpecBase.subplots` method.  For example, we can reduce the height
 # between vertical subplots using ``add_gridspec(hspace=0)``.
 #