DOC: add example, build toc for Figure

jklymak · jklymak · commit de926516c5d8 · 2020-09-16T16:12:19.000-07:00
diff --git a/doc/api/figure_api.rst b/doc/api/figure_api.rst
@@ -15,8 +15,10 @@ Classes
    :toctree: _as_gen/
    :template: autosummary.rst
    :nosignatures:
+   :inhereted-members:
 
    AxesStack
+   SubPanel
    Figure
    SubplotParams
 
diff --git a/examples/subplots_axes_and_figures/subpanels.py b/examples/subplots_axes_and_figures/subpanels.py
@@ -0,0 +1,50 @@
+"""
+================
+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):
+    pc = 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)
+    return pc
+
+
+# gridspec inside gridspec
+fig = plt.figure(constrained_layout=True, figsize=(10, 4))
+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:
+ pc = example_plot(ax)
+subpanels[0].suptitle('Left plots', fontsize='x-large')
+subpanels[0].colorbar(pc, shrink=0.6, ax=axsLeft, location='bottom')
+
+axsRight = subpanels[1].subplots(3, 1, sharex=True)
+for nn, ax in enumerate(axsRight):
+ pc = example_plot(ax, hide_labels=True)
+ if nn == 2:
+     ax.set_xlabel('xlabel')
+ if nn == 1:
+     ax.set_ylabel('ylabel')
+subpanels[1].set_facecolor('0.85')
+subpanels[1].colorbar(pc, shrink=0.6, ax=axsRight)
+subpanels[1].suptitle('Right plots', fontsize='x-large')
+
+fig.suptitle('Figure suptitle', fontsize='xx-large')
+
+plt.show()
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1,8 +1,14 @@
 """
 `matplotlib.figure` implements the following classes:
 
+
 `Figure`
     Top level `~matplotlib.artist.Artist`, which holds all plot elements.
+    Many methods are implimented in `PanelBase`.
+
+`SubPanel`
+    A logical figure inside a figure, usually added to a figure or parent
+    `SubPanel` with `.add_subpanel` or `.subpanels` methods.  
 
 `SubplotParams`
     Control the default spacing between subplots.
@@ -221,7 +227,7 @@ def update(self, left=None, bottom=None, right=None, top=None,
 class PanelBase(Artist):
     """
     Base class for `.figure.Figure` and `.figure.SubPanel` containing the
-    methods that add artists to the figure, create axes, etc.
+    methods that add artists to the figure or panel, create axes, etc.
     """
     def __init__(self):
         super().__init__()
@@ -254,6 +260,7 @@ def __init__(self):
         self.panels = []
         self._suptitle = None
         self.stale = True
+        self.suppressComposite = None
 
     def _get_draw_artists(self, renderer):
         """Also runs apply_aspect"""
